@logtape/syslog 0.12.0-dev.199

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @logtape/syslog
+
+[![JSR](https://jsr.io/badges/@logtape/syslog)](https://jsr.io/@logtape/syslog)
+[![npm](https://img.shields.io/npm/v/@logtape/syslog)](https://www.npmjs.com/package/@logtape/syslog)
+
+Syslog sink for [LogTape]. This package provides a syslog sink that sends log messages to a syslog server following the [RFC 5424] specification.
+
+## Features
+
+- **RFC 5424 compliant**: Follows the official syslog protocol specification
+- **Multiple transports**: Supports both UDP and TCP protocols
+- **Cross-runtime**: Works on Deno, Node.js, and Bun
+- **Non-blocking**: Asynchronous message sending with proper cleanup
+- **Configurable**: Extensive configuration options for facility, hostname, etc.
+- **Structured logging**: Optional structured data support
+- **Zero dependencies**: No external dependencies
+
+## Installation
+
+::: code-group
+
+```sh [Deno]
+deno add jsr:@logtape/syslog
+```
+
+```sh [npm]
+npm add @logtape/syslog
+```
+
+```sh [pnpm]
+pnpm add @logtape/syslog
+```
+
+```sh [Yarn]
+yarn add @logtape/syslog
+```
+
+```sh [Bun]
+bun add @logtape/syslog
+```
+
+:::
+
+## Usage
+
+```typescript
+import { configure } from "@logtape/logtape";
+import { getSyslogSink } from "@logtape/syslog";
+
+await configure({
+  sinks: {
+    syslog: getSyslogSink({
+      hostname: "syslog.example.com",
+      port: 514,
+      protocol: "udp",
+      facility: "local0",
+      appName: "my-app",
+    }),
+  },
+  loggers: [
+    { category: [], sinks: ["syslog"], level: "info" },
+  ],
+});
+```
+
+## Configuration Options
+
+- **hostname**: Syslog server hostname (default: "localhost")
+- **port**: Syslog server port (default: 514)
+- **protocol**: Transport protocol "udp" or "tcp" (default: "udp")
+- **facility**: Syslog facility (default: "local0")
+- **appName**: Application name in syslog messages (default: "logtape")
+- **syslogHostname**: Hostname field in syslog messages
+- **processId**: Process ID field in syslog messages
+- **timeout**: Connection timeout in milliseconds (default: 5000)
+- **includeStructuredData**: Include LogTape properties as structured data (default: false)
+
+## Facilities
+
+Supports all RFC 5424 facilities:
+- System facilities: `kernel`, `user`, `mail`, `daemon`, `security`, `syslog`, `lpr`, `news`, `uucp`, `cron`, `authpriv`, `ftp`, `ntp`, `logaudit`, `logalert`, `clock`
+- Local facilities: `local0` through `local7`
+
+## License
+
+MIT License. See [LICENSE](../LICENSE) for details.
+
+[LogTape]: https://logtape.org/
+[RFC 5424]: https://tools.ietf.org/rfc/rfc5424.txt

package/deno.json

@@ -0,0 +1,34 @@
+{
+  "name": "@logtape/syslog",
+  "version": "0.12.0-dev.199+b454c29f",
+  "license": "MIT",
+  "exports": "./mod.ts",
+  "exclude": [
+    "coverage/",
+    "npm/",
+    ".dnt-import-map.json"
+  ],
+  "tasks": {
+    "build": "pnpm build",
+    "test": "deno test --allow-net --allow-env=TEMP,TMP,TMPDIR,HOSTNAME --allow-sys",
+    "test:node": {
+      "dependencies": [
+        "build"
+      ],
+      "command": "node --experimental-transform-types --test"
+    },
+    "test:bun": {
+      "dependencies": [
+        "build"
+      ],
+      "command": "bun test"
+    },
+    "test-all": {
+      "dependencies": [
+        "test",
+        "test:node",
+        "test:bun"
+      ]
+    }
+  }
+}

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/mod.cjs

@@ -0,0 +1,3 @@
+const require_syslog = require('./syslog.cjs');
+
+exports.getSyslogSink = require_syslog.getSyslogSink;

package/dist/mod.d.cts

@@ -0,0 +1,2 @@
+import { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink } from "./syslog.cjs";
+export { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink };

package/dist/mod.d.ts

@@ -0,0 +1,2 @@
+import { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink } from "./syslog.js";
+export { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink };

package/dist/mod.js

@@ -0,0 +1,3 @@
+import { getSyslogSink } from "./syslog.js";
+
+export { getSyslogSink };

package/dist/syslog.cjs

@@ -0,0 +1,468 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_dgram = require_rolldown_runtime.__toESM(require("node:dgram"));
+const node_net = require_rolldown_runtime.__toESM(require("node:net"));
+const node_os = require_rolldown_runtime.__toESM(require("node:os"));
+const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+
+//#region syslog.ts
+/**
+* Syslog facility code mapping.
+* @since 0.12.0
+*/
+const FACILITY_CODES = {
+	kernel: 0,
+	user: 1,
+	mail: 2,
+	daemon: 3,
+	security: 4,
+	syslog: 5,
+	lpr: 6,
+	news: 7,
+	uucp: 8,
+	cron: 9,
+	authpriv: 10,
+	ftp: 11,
+	ntp: 12,
+	logaudit: 13,
+	logalert: 14,
+	clock: 15,
+	local0: 16,
+	local1: 17,
+	local2: 18,
+	local3: 19,
+	local4: 20,
+	local5: 21,
+	local6: 22,
+	local7: 23
+};
+/**
+* Syslog severity levels as defined in RFC 5424.
+* @since 0.12.0
+*/
+const SEVERITY_LEVELS = {
+	fatal: 0,
+	error: 3,
+	warning: 4,
+	info: 6,
+	debug: 7,
+	trace: 7
+};
+/**
+* Calculates the priority value for a syslog message.
+* Priority = Facility * 8 + Severity
+* @since 0.12.0
+*/
+function calculatePriority(facility, severity) {
+	const facilityCode = FACILITY_CODES[facility];
+	return facilityCode * 8 + severity;
+}
+/**
+* Formats a timestamp (number) as RFC 3339 timestamp for syslog.
+* @since 0.12.0
+*/
+function formatTimestamp(timestamp) {
+	return new Date(timestamp).toISOString();
+}
+/**
+* Escapes special characters in structured data values.
+* @since 0.12.0
+*/
+function escapeStructuredDataValue(value) {
+	return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/]/g, "\\]");
+}
+/**
+* Formats structured data from log record properties.
+* @since 0.12.0
+*/
+function formatStructuredData(record, structuredDataId) {
+	if (!record.properties || Object.keys(record.properties).length === 0) return "-";
+	const elements = [];
+	for (const [key, value] of Object.entries(record.properties)) {
+		const escapedValue = escapeStructuredDataValue(String(value));
+		elements.push(`${key}="${escapedValue}"`);
+	}
+	return `[${structuredDataId} ${elements.join(" ")}]`;
+}
+/**
+* Formats a log record as RFC 5424 syslog message.
+* @since 0.12.0
+*/
+function formatSyslogMessage(record, options) {
+	const severity = SEVERITY_LEVELS[record.level];
+	const priority = calculatePriority(options.facility, severity);
+	const timestamp = formatTimestamp(record.timestamp);
+	const hostname$1 = options.syslogHostname || "-";
+	const appName = options.appName || "-";
+	const processId = options.processId || "-";
+	const msgId = "-";
+	let structuredData = "-";
+	if (options.includeStructuredData) structuredData = formatStructuredData(record, options.structuredDataId);
+	let message = "";
+	for (let i = 0; i < record.message.length; i++) if (i % 2 === 0) message += record.message[i];
+	else message += JSON.stringify(record.message[i]);
+	return `<${priority}>1 ${timestamp} ${hostname$1} ${appName} ${processId} ${msgId} ${structuredData} ${message}`;
+}
+/**
+* Gets the system hostname.
+* @since 0.12.0
+*/
+function getSystemHostname() {
+	try {
+		if (typeof Deno !== "undefined" && Deno.hostname) return Deno.hostname();
+		return (0, node_os.hostname)();
+	} catch {
+		return node_process.default.env.HOSTNAME || "localhost";
+	}
+}
+/**
+* Gets the current process ID.
+* @since 0.12.0
+*/
+function getProcessId() {
+	try {
+		if (typeof Deno !== "undefined" && Deno.pid) return Deno.pid.toString();
+		return node_process.default.pid.toString();
+	} catch {
+		return "-";
+	}
+}
+/**
+* Deno UDP syslog connection implementation.
+* @since 0.12.0
+*/
+var DenoUdpSyslogConnection = class {
+	encoder = new TextEncoder();
+	constructor(hostname$1, port, timeout) {
+		this.hostname = hostname$1;
+		this.port = port;
+		this.timeout = timeout;
+	}
+	connect() {}
+	send(message) {
+		const data = this.encoder.encode(message);
+		try {
+			const socket = (0, node_dgram.createSocket)("udp4");
+			if (this.timeout > 0) return new Promise((resolve, reject) => {
+				const timeout = setTimeout(() => {
+					socket.close();
+					reject(new Error("UDP send timeout"));
+				}, this.timeout);
+				socket.send(data, this.port, this.hostname, (error) => {
+					clearTimeout(timeout);
+					socket.close();
+					if (error) reject(error);
+					else resolve();
+				});
+			});
+			else return new Promise((resolve, reject) => {
+				socket.send(data, this.port, this.hostname, (error) => {
+					socket.close();
+					if (error) reject(error);
+					else resolve();
+				});
+			});
+		} catch (error) {
+			throw new Error(`Failed to send syslog message: ${error}`);
+		}
+	}
+	close() {}
+};
+/**
+* Node.js UDP syslog connection implementation.
+* @since 0.12.0
+*/
+var NodeUdpSyslogConnection = class {
+	encoder = new TextEncoder();
+	constructor(hostname$1, port, timeout) {
+		this.hostname = hostname$1;
+		this.port = port;
+		this.timeout = timeout;
+	}
+	connect() {}
+	send(message) {
+		const data = this.encoder.encode(message);
+		try {
+			const socket = (0, node_dgram.createSocket)("udp4");
+			return new Promise((resolve, reject) => {
+				const timeout = setTimeout(() => {
+					socket.close();
+					reject(new Error("UDP send timeout"));
+				}, this.timeout);
+				socket.send(data, this.port, this.hostname, (error) => {
+					clearTimeout(timeout);
+					socket.close();
+					if (error) reject(error);
+					else resolve();
+				});
+			});
+		} catch (error) {
+			throw new Error(`Failed to send syslog message: ${error}`);
+		}
+	}
+	close() {}
+};
+/**
+* Deno TCP syslog connection implementation.
+* @since 0.12.0
+*/
+var DenoTcpSyslogConnection = class {
+	connection;
+	encoder = new TextEncoder();
+	constructor(hostname$1, port, timeout) {
+		this.hostname = hostname$1;
+		this.port = port;
+		this.timeout = timeout;
+	}
+	async connect() {
+		try {
+			if (this.timeout > 0) {
+				const controller = new AbortController();
+				const timeoutId = setTimeout(() => {
+					controller.abort();
+				}, this.timeout);
+				try {
+					this.connection = await Deno.connect({
+						hostname: this.hostname,
+						port: this.port,
+						transport: "tcp",
+						signal: controller.signal
+					});
+					clearTimeout(timeoutId);
+				} catch (error) {
+					clearTimeout(timeoutId);
+					if (controller.signal.aborted) throw new Error("TCP connection timeout");
+					throw error;
+				}
+			} else this.connection = await Deno.connect({
+				hostname: this.hostname,
+				port: this.port,
+				transport: "tcp"
+			});
+		} catch (error) {
+			throw new Error(`Failed to connect to syslog server: ${error}`);
+		}
+	}
+	async send(message) {
+		if (!this.connection) throw new Error("Connection not established");
+		const data = this.encoder.encode(message + "\n");
+		try {
+			if (this.timeout > 0) {
+				const writePromise = this.connection.write(data);
+				const timeoutPromise = new Promise((_, reject) => {
+					setTimeout(() => {
+						reject(new Error("TCP send timeout"));
+					}, this.timeout);
+				});
+				await Promise.race([writePromise, timeoutPromise]);
+			} else await this.connection.write(data);
+		} catch (error) {
+			throw new Error(`Failed to send syslog message: ${error}`);
+		}
+	}
+	close() {
+		if (this.connection) {
+			try {
+				this.connection.close();
+			} catch {}
+			this.connection = void 0;
+		}
+	}
+};
+/**
+* Node.js TCP syslog connection implementation.
+* @since 0.12.0
+*/
+var NodeTcpSyslogConnection = class {
+	connection;
+	encoder = new TextEncoder();
+	constructor(hostname$1, port, timeout) {
+		this.hostname = hostname$1;
+		this.port = port;
+		this.timeout = timeout;
+	}
+	connect() {
+		try {
+			return new Promise((resolve, reject) => {
+				const socket = new node_net.Socket();
+				const timeout = setTimeout(() => {
+					socket.destroy();
+					reject(new Error("TCP connection timeout"));
+				}, this.timeout);
+				socket.on("connect", () => {
+					clearTimeout(timeout);
+					this.connection = socket;
+					resolve();
+				});
+				socket.on("error", (error) => {
+					clearTimeout(timeout);
+					reject(error);
+				});
+				socket.connect(this.port, this.hostname);
+			});
+		} catch (error) {
+			throw new Error(`Failed to connect to syslog server: ${error}`);
+		}
+	}
+	send(message) {
+		if (!this.connection) throw new Error("Connection not established");
+		const data = this.encoder.encode(message + "\n");
+		try {
+			return new Promise((resolve, reject) => {
+				this.connection.write(data, (error) => {
+					if (error) reject(error);
+					else resolve();
+				});
+			});
+		} catch (error) {
+			throw new Error(`Failed to send syslog message: ${error}`);
+		}
+	}
+	close() {
+		if (this.connection) {
+			try {
+				this.connection.end();
+			} catch {}
+			this.connection = void 0;
+		}
+	}
+};
+/**
+* Creates a syslog sink that sends log messages to a syslog server using the
+* RFC 5424 syslog protocol format.
+*
+* This sink supports both UDP and TCP protocols for reliable log transmission
+* to centralized logging systems. It automatically formats log records according
+* to RFC 5424 specification, including structured data support for log properties.
+*
+* ## Features
+*
+* - **RFC 5424 Compliance**: Full implementation of the RFC 5424 syslog protocol
+* - **Cross-Runtime Support**: Works with Deno, Node.js, Bun, and browsers
+* - **Multiple Protocols**: Supports both UDP (fire-and-forget) and TCP (reliable) delivery
+* - **Structured Data**: Automatically includes log record properties as RFC 5424 structured data
+* - **Facility Support**: All standard syslog facilities (kern, user, mail, daemon, local0-7, etc.)
+* - **Automatic Escaping**: Proper escaping of special characters in structured data values
+* - **Connection Management**: Automatic connection handling with configurable timeouts
+*
+* ## Protocol Differences
+*
+* - **UDP**: Fast, connectionless delivery suitable for high-throughput logging.
+*   Messages may be lost during network issues but has minimal performance impact.
+* - **TCP**: Reliable, connection-based delivery that ensures message delivery.
+*   Higher overhead but guarantees that log messages reach the server.
+*
+* @param options Configuration options for the syslog sink
+* @returns A sink function that sends log records to the syslog server, implementing AsyncDisposable for proper cleanup
+*
+* @example Basic usage with default options
+* ```typescript
+* import { configure } from "@logtape/logtape";
+* import { getSyslogSink } from "@logtape/syslog";
+*
+* await configure({
+*   sinks: {
+*     syslog: getSyslogSink(),  // Sends to localhost:514 via UDP
+*   },
+*   loggers: [
+*     { category: [], sinks: ["syslog"], lowestLevel: "info" },
+*   ],
+* });
+* ```
+*
+* @example Custom syslog server configuration
+* ```typescript
+* import { configure } from "@logtape/logtape";
+* import { getSyslogSink } from "@logtape/syslog";
+*
+* await configure({
+*   sinks: {
+*     syslog: getSyslogSink({
+*       hostname: "log-server.example.com",
+*       port: 1514,
+*       protocol: "tcp",
+*       facility: "mail",
+*       appName: "my-application",
+*       timeout: 10000,
+*     }),
+*   },
+*   loggers: [
+*     { category: [], sinks: ["syslog"], lowestLevel: "debug" },
+*   ],
+* });
+* ```
+*
+* @example Using structured data for log properties
+* ```typescript
+* import { configure, getLogger } from "@logtape/logtape";
+* import { getSyslogSink } from "@logtape/syslog";
+*
+* await configure({
+*   sinks: {
+*     syslog: getSyslogSink({
+*       includeStructuredData: true,
+*       structuredDataId: "myapp@12345",
+*     }),
+*   },
+*   loggers: [
+*     { category: [], sinks: ["syslog"], lowestLevel: "info" },
+*   ],
+* });
+*
+* const logger = getLogger();
+* // This will include userId and action as structured data
+* logger.info("User action completed", { userId: 123, action: "login" });
+* // Results in: <134>1 2024-01-01T12:00:00.000Z hostname myapp 1234 - [myapp@12345 userId="123" action="login"] User action completed
+* ```
+*
+* @since 0.12.0
+* @see {@link https://tools.ietf.org/html/rfc5424} RFC 5424 - The Syslog Protocol
+* @see {@link SyslogSinkOptions} for detailed configuration options
+*/
+function getSyslogSink(options = {}) {
+	const hostname$1 = options.hostname ?? "localhost";
+	const port = options.port ?? 514;
+	const protocol = options.protocol ?? "udp";
+	const facility = options.facility ?? "local0";
+	const appName = options.appName ?? "logtape";
+	const syslogHostname = options.syslogHostname ?? getSystemHostname();
+	const processId = options.processId ?? getProcessId();
+	const timeout = options.timeout ?? 5e3;
+	const includeStructuredData = options.includeStructuredData ?? false;
+	const structuredDataId = options.structuredDataId ?? "logtape@32473";
+	const formatOptions = {
+		facility,
+		appName,
+		syslogHostname,
+		processId,
+		includeStructuredData,
+		structuredDataId
+	};
+	const connection = (() => {
+		if (typeof Deno !== "undefined") return protocol === "tcp" ? new DenoTcpSyslogConnection(hostname$1, port, timeout) : new DenoUdpSyslogConnection(hostname$1, port, timeout);
+		else return protocol === "tcp" ? new NodeTcpSyslogConnection(hostname$1, port, timeout) : new NodeUdpSyslogConnection(hostname$1, port, timeout);
+	})();
+	let isConnected = false;
+	let lastPromise = Promise.resolve();
+	const sink = (record) => {
+		const syslogMessage = formatSyslogMessage(record, formatOptions);
+		lastPromise = lastPromise.then(async () => {
+			if (!isConnected) {
+				await connection.connect();
+				isConnected = true;
+			}
+			await connection.send(syslogMessage);
+		}).catch((error) => {
+			isConnected = false;
+			throw error;
+		});
+	};
+	sink[Symbol.asyncDispose] = async () => {
+		await lastPromise.catch(() => {});
+		connection.close();
+		isConnected = false;
+	};
+	return sink;
+}
+
+//#endregion
+exports.getSyslogSink = getSyslogSink;