@logtape/syslog 0.12.0-dev.199

package/dist/syslog.d.cts

@@ -0,0 +1,173 @@
+import { Sink } from "@logtape/logtape";
+
+//#region syslog.d.ts
+
+/**
+ * Syslog protocol type.
+ * @since 0.12.0
+ */
+type SyslogProtocol = "udp" | "tcp";
+/**
+ * Syslog facility codes as defined in RFC 5424.
+ * @since 0.12.0
+ */
+type SyslogFacility = "kernel" | "user" | "mail" | "daemon" | "security" | "syslog" | "lpr" | "news" | "uucp" | "cron" | "authpriv" | "ftp" | "ntp" | "logaudit" | "logalert" | "clock" | "local0" | "local1" | "local2" | "local3" | "local4" | "local5" | "local6" | "local7";
+/**
+ * Options for the syslog sink.
+ * @since 0.12.0
+ */
+interface SyslogSinkOptions {
+  /**
+   * The hostname or IP address of the syslog server.
+   * @default "localhost"
+   */
+  readonly hostname?: string;
+  /**
+   * The port number of the syslog server.
+   * @default 514
+   */
+  readonly port?: number;
+  /**
+   * The protocol to use for sending syslog messages.
+   * @default "udp"
+   */
+  readonly protocol?: SyslogProtocol;
+  /**
+   * The syslog facility to use for all messages.
+   * @default "local0"
+   */
+  readonly facility?: SyslogFacility;
+  /**
+   * The application name to include in syslog messages.
+   * @default "logtape"
+   */
+  readonly appName?: string;
+  /**
+   * The hostname to include in syslog messages.
+   * If not provided, the system hostname will be used.
+   */
+  readonly syslogHostname?: string;
+  /**
+   * The process ID to include in syslog messages.
+   * If not provided, the current process ID will be used.
+   */
+  readonly processId?: string;
+  /**
+   * Connection timeout in milliseconds.
+   * @default 5000
+   */
+  readonly timeout?: number;
+  /**
+   * Whether to include structured data in syslog messages.
+   * @default `false`
+   */
+  readonly includeStructuredData?: boolean;
+  /**
+   * The structured data ID to use for log properties.
+   * Should follow the format "name@private-enterprise-number".
+   * @default "logtape@32473"
+   */
+  readonly structuredDataId?: string;
+}
+/**
+ * Base interface for syslog connections.
+ * @since 0.12.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
+ */
+declare function getSyslogSink(options?: SyslogSinkOptions): Sink & AsyncDisposable;
+//# sourceMappingURL=syslog.d.ts.map
+//#endregion
+export { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink };
+//# sourceMappingURL=syslog.d.cts.map

package/dist/syslog.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syslog.d.cts","names":[],"sources":["../syslog.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AAMA;AA0EiB,KAhFL,cAAA,GAgFsB,KAAA,GAAA,KAAA;;;;AAuBE;AA0iBpB,KA3oBJ,cAAA,GA2oBiB,QAAA,GAAA,MAAA,GAAA,MAAA,GAAA,QAAA,GAAA,UAAA,GAAA,QAAA,GAAA,KAAA,GAAA,MAAA,GAAA,MAAA,GAAA,MAAA,GAAA,UAAA,GAAA,KAAA,GAAA,KAAA,GAAA,UAAA,GAAA,UAAA,GAAA,OAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA;;;;;AAEJ,UAnkBR,iBAAA,CAmkBQ;;;;;;;;;;;;;;;sBAljBH;;;;;sBAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0iBN,aAAA,WACL,oBACR,OAAO"}

package/dist/syslog.d.ts

@@ -0,0 +1,173 @@
+import { Sink } from "@logtape/logtape";
+
+//#region syslog.d.ts
+
+/**
+ * Syslog protocol type.
+ * @since 0.12.0
+ */
+type SyslogProtocol = "udp" | "tcp";
+/**
+ * Syslog facility codes as defined in RFC 5424.
+ * @since 0.12.0
+ */
+type SyslogFacility = "kernel" | "user" | "mail" | "daemon" | "security" | "syslog" | "lpr" | "news" | "uucp" | "cron" | "authpriv" | "ftp" | "ntp" | "logaudit" | "logalert" | "clock" | "local0" | "local1" | "local2" | "local3" | "local4" | "local5" | "local6" | "local7";
+/**
+ * Options for the syslog sink.
+ * @since 0.12.0
+ */
+interface SyslogSinkOptions {
+  /**
+   * The hostname or IP address of the syslog server.
+   * @default "localhost"
+   */
+  readonly hostname?: string;
+  /**
+   * The port number of the syslog server.
+   * @default 514
+   */
+  readonly port?: number;
+  /**
+   * The protocol to use for sending syslog messages.
+   * @default "udp"
+   */
+  readonly protocol?: SyslogProtocol;
+  /**
+   * The syslog facility to use for all messages.
+   * @default "local0"
+   */
+  readonly facility?: SyslogFacility;
+  /**
+   * The application name to include in syslog messages.
+   * @default "logtape"
+   */
+  readonly appName?: string;
+  /**
+   * The hostname to include in syslog messages.
+   * If not provided, the system hostname will be used.
+   */
+  readonly syslogHostname?: string;
+  /**
+   * The process ID to include in syslog messages.
+   * If not provided, the current process ID will be used.
+   */
+  readonly processId?: string;
+  /**
+   * Connection timeout in milliseconds.
+   * @default 5000
+   */
+  readonly timeout?: number;
+  /**
+   * Whether to include structured data in syslog messages.
+   * @default `false`
+   */
+  readonly includeStructuredData?: boolean;
+  /**
+   * The structured data ID to use for log properties.
+   * Should follow the format "name@private-enterprise-number".
+   * @default "logtape@32473"
+   */
+  readonly structuredDataId?: string;
+}
+/**
+ * Base interface for syslog connections.
+ * @since 0.12.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
+ */
+declare function getSyslogSink(options?: SyslogSinkOptions): Sink & AsyncDisposable;
+//# sourceMappingURL=syslog.d.ts.map
+//#endregion
+export { SyslogFacility, SyslogProtocol, SyslogSinkOptions, getSyslogSink };
+//# sourceMappingURL=syslog.d.ts.map

package/dist/syslog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syslog.d.ts","names":[],"sources":["../syslog.ts"],"sourcesContent":[],"mappings":";;;;;;AAUA;AAMA;AA0EiB,KAhFL,cAAA,GAgFsB,KAAA,GAAA,KAAA;;;;AAuBE;AA0iBpB,KA3oBJ,cAAA,GA2oBiB,QAAA,GAAA,MAAA,GAAA,MAAA,GAAA,QAAA,GAAA,UAAA,GAAA,QAAA,GAAA,KAAA,GAAA,MAAA,GAAA,MAAA,GAAA,MAAA,GAAA,UAAA,GAAA,KAAA,GAAA,KAAA,GAAA,UAAA,GAAA,UAAA,GAAA,OAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA,GAAA,QAAA;;;;;AAEJ,UAnkBR,iBAAA,CAmkBQ;;;;;;;;;;;;;;;sBAljBH;;;;;sBAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0iBN,aAAA,WACL,oBACR,OAAO"}