@panguard-ai/core 0.1.0

package/dist/adapters/syslog-adapter.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Syslog receiver adapter (RFC 5424)
+ * Syslog 接收器對接器 (RFC 5424)
+ *
+ * Receives syslog messages over UDP, parses RFC 5424 format, and converts
+ * them to standardized AdapterAlerts. Supports buffered alert retrieval
+ * and callback-based real-time alert notification.
+ * 透過 UDP 接收 syslog 訊息，解析 RFC 5424 格式，並將其轉換為
+ * 標準化的 AdapterAlert。支援緩衝告警取得和基於回呼的即時告警通知。
+ *
+ * @module @panguard-ai/core/adapters/syslog-adapter
+ */
+import type { AdapterConfig, AdapterAlert } from './types.js';
+import { BaseAdapter } from './base-adapter.js';
+/**
+ * Parsed RFC 5424 syslog message fields
+ * 已解析的 RFC 5424 syslog 訊息欄位
+ */
+interface ParsedSyslogMessage {
+    /** Syslog facility code (0-23) / Syslog 設施碼 (0-23) */
+    facility: number;
+    /** Syslog severity code (0-7) / Syslog 嚴重等級碼 (0-7) */
+    severityCode: number;
+    /** RFC 5424 version / RFC 5424 版本 */
+    version: number;
+    /** Message timestamp (ISO 8601 or NILVALUE) / 訊息時間戳（ISO 8601 或 NILVALUE） */
+    timestamp: string;
+    /** Hostname / 主機名稱 */
+    hostname: string;
+    /** Application name / 應用程式名稱 */
+    appName: string;
+    /** Process ID / 行程 ID */
+    procId: string;
+    /** Message ID / 訊息 ID */
+    msgId: string;
+    /** Structured data / 結構化資料 */
+    structuredData: string;
+    /** Message body / 訊息本體 */
+    message: string;
+}
+/**
+ * Parse a raw syslog message string into structured fields
+ * 將原始 syslog 訊息字串解析為結構化欄位
+ *
+ * Supports RFC 5424 format. Falls back to a best-effort parse for
+ * non-conforming messages by treating the entire string as the message body.
+ * 支援 RFC 5424 格式。對於不符合格式的訊息，會以盡力解析方式
+ * 將整個字串視為訊息本體。
+ *
+ * @param raw - Raw syslog message string / 原始 syslog 訊息字串
+ * @returns Parsed syslog message fields / 已解析的 syslog 訊息欄位
+ */
+export declare function parseSyslogMessage(raw: string): ParsedSyslogMessage;
+/**
+ * Callback type for real-time alert notification
+ * 即時告警通知的回呼型別
+ */
+export type SyslogAlertCallback = (alert: AdapterAlert) => void;
+/**
+ * Syslog receiver security adapter (RFC 5424)
+ * Syslog 接收器安全對接器 (RFC 5424)
+ *
+ * Listens for syslog messages on a UDP socket, parses RFC 5424 format,
+ * buffers parsed alerts, and provides both callback-based real-time
+ * notification and pull-based alert retrieval.
+ *
+ * 在 UDP socket 上監聽 syslog 訊息，解析 RFC 5424 格式，
+ * 緩衝已解析的告警，並提供基於回呼的即時通知和拉取式告警取得。
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SyslogAdapter({ enabled: true });
+ *
+ * // Set up real-time callback / 設定即時回呼
+ * adapter.onAlert((alert) => {
+ *   console.log('New syslog alert:', alert);
+ * });
+ *
+ * // Start listening on port 514 / 開始在埠 514 上監聽
+ * await adapter.start(514);
+ *
+ * // Later: retrieve buffered alerts / 稍後：取得緩衝的告警
+ * const alerts = await adapter.getAlerts();
+ *
+ * // Stop listening / 停止監聽
+ * adapter.stop();
+ * ```
+ */
+export declare class SyslogAdapter extends BaseAdapter {
+    /** @inheritdoc */
+    readonly name = "Syslog Receiver";
+    /** @inheritdoc */
+    readonly type = "syslog";
+    /**
+     * UDP socket for receiving syslog messages
+     * 用於接收 syslog 訊息的 UDP socket
+     */
+    private socket;
+    /**
+     * Buffer of alerts received since last getAlerts() call
+     * 自上次 getAlerts() 呼叫以來接收的告警緩衝區
+     */
+    private alertBuffer;
+    /**
+     * Real-time alert callback
+     * 即時告警回呼
+     */
+    private alertCallback;
+    /**
+     * Whether the socket is currently listening
+     * socket 是否正在監聽
+     */
+    private listening;
+    /**
+     * Port the socket is listening on
+     * socket 正在監聽的埠
+     */
+    private listenPort;
+    /**
+     * Create a new SyslogAdapter instance
+     * 建立新的 SyslogAdapter 實例
+     *
+     * @param config - Adapter configuration / 對接器配置
+     */
+    constructor(config?: AdapterConfig);
+    /**
+     * Register a callback for real-time alert notification
+     * 註冊即時告警通知的回呼
+     *
+     * The callback is invoked for each parsed syslog message as it arrives.
+     * Only one callback can be registered at a time; setting a new one
+     * replaces the previous.
+     * 每收到一筆已解析的 syslog 訊息就會呼叫此回呼。
+     * 同一時間只能註冊一個回呼；設定新的會取代前一個。
+     *
+     * @param callback - Alert callback function / 告警回呼函式
+     */
+    onAlert(callback: SyslogAlertCallback): void;
+    /**
+     * Check if the syslog receiver is available (i.e. listening)
+     * 檢查 syslog 接收器是否可用（即正在監聽）
+     *
+     * @returns True if the UDP socket is bound and listening / 若 UDP socket 已綁定且正在監聽則回傳 true
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Start the UDP syslog receiver
+     * 啟動 UDP syslog 接收器
+     *
+     * Binds a UDP4 socket to the specified port and begins listening
+     * for incoming syslog messages. Each message is parsed according to
+     * RFC 5424 and added to the alert buffer.
+     * 將 UDP4 socket 綁定到指定埠並開始監聽傳入的 syslog 訊息。
+     * 每筆訊息都會依 RFC 5424 解析並新增到告警緩衝區。
+     *
+     * @param port - UDP port to listen on (default: 514) / 要監聽的 UDP 埠（預設：514）
+     * @returns Promise that resolves when the socket is bound / socket 綁定後 resolve 的 Promise
+     */
+    start(port?: number): Promise<void>;
+    /**
+     * Stop the UDP syslog receiver
+     * 停止 UDP syslog 接收器
+     *
+     * Closes the UDP socket and stops listening for messages.
+     * The alert buffer is preserved and can still be read via getAlerts().
+     * 關閉 UDP socket 並停止監聽訊息。
+     * 告警緩衝區會被保留，仍可透過 getAlerts() 讀取。
+     */
+    stop(): void;
+    /**
+     * Retrieve buffered alerts and clear the buffer
+     * 取得緩衝的告警並清除緩衝區
+     *
+     * Returns all alerts accumulated since the last call to getAlerts().
+     * Optionally filters by a cutoff date. The buffer is cleared after
+     * retrieval to prevent duplicate processing.
+     * 回傳自上次呼叫 getAlerts() 以來累積的所有告警。
+     * 可選依截止日期過濾。取得後會清除緩衝區以防止重複處理。
+     *
+     * @param since - Optional cutoff date / 可選截止日期
+     * @returns Array of buffered adapter alerts / 緩衝的對接器告警陣列
+     */
+    getAlerts(since?: Date): Promise<AdapterAlert[]>;
+    /**
+     * Get the current buffer size (number of pending alerts)
+     * 取得目前緩衝區大小（待處理告警數量）
+     *
+     * @returns Number of alerts in the buffer / 緩衝區中的告警數量
+     */
+    getBufferSize(): number;
+    /**
+     * Check if the receiver is currently listening
+     * 檢查接收器是否正在監聽
+     *
+     * @returns True if listening / 若正在監聽則回傳 true
+     */
+    isListening(): boolean;
+    /**
+     * Get the port the receiver is listening on
+     * 取得接收器正在監聽的埠
+     *
+     * @returns Port number, or 0 if not listening / 埠號，若未監聽則為 0
+     */
+    getPort(): number;
+}
+export {};
+//# sourceMappingURL=syslog-adapter.d.ts.map

package/dist/adapters/syslog-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syslog-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/syslog-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA8DhD;;;GAGG;AACH,UAAU,mBAAmB;IAC3B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAkEnE;AA4BD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C,kBAAkB;IAClB,QAAQ,CAAC,IAAI,qBAAqB;IAElC,kBAAkB;IAClB,QAAQ,CAAC,IAAI,YAAY;IAEzB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAA6B;IAE3C;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAsB;IAEzC;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAoC;IAEzD;;;OAGG;IACH,OAAO,CAAC,SAAS,CAAS;IAE1B;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;OAKG;gBACS,MAAM,GAAE,aAAiC;IAIrD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAI5C;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,IAAI,GAAE,MAA4B,GAAG,OAAO,CAAC,IAAI,CAAC;IA6ExD;;;;;;;;OAQG;IACH,IAAI,IAAI,IAAI;IAcZ;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAyBtD;;;;;OAKG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;;OAKG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;OAKG;IACH,OAAO,IAAI,MAAM;CAGlB"}

package/dist/adapters/syslog-adapter.js

@@ -0,0 +1,432 @@
+/**
+ * Syslog receiver adapter (RFC 5424)
+ * Syslog 接收器對接器 (RFC 5424)
+ *
+ * Receives syslog messages over UDP, parses RFC 5424 format, and converts
+ * them to standardized AdapterAlerts. Supports buffered alert retrieval
+ * and callback-based real-time alert notification.
+ * 透過 UDP 接收 syslog 訊息，解析 RFC 5424 格式，並將其轉換為
+ * 標準化的 AdapterAlert。支援緩衝告警取得和基於回呼的即時告警通知。
+ *
+ * @module @panguard-ai/core/adapters/syslog-adapter
+ */
+import dgram from 'node:dgram';
+import { randomUUID } from 'node:crypto';
+import { BaseAdapter } from './base-adapter.js';
+/**
+ * Default UDP port for syslog reception
+ * syslog 接收的預設 UDP 埠
+ */
+const DEFAULT_SYSLOG_PORT = 514;
+/**
+ * Maximum buffer size for stored alerts before oldest are discarded
+ * 在丟棄最舊告警前的最大緩衝區大小
+ */
+const MAX_BUFFER_SIZE = 10000;
+/**
+ * RFC 5424 syslog severity levels (0-7)
+ * RFC 5424 syslog 嚴重等級 (0-7)
+ *
+ * See https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+ */
+const SYSLOG_SEVERITY_MAP = {
+    0: 'critical', // Emergency / 緊急
+    1: 'critical', // Alert / 警報
+    2: 'critical', // Critical / 重大
+    3: 'high', // Error / 錯誤
+    4: 'medium', // Warning / 警告
+    5: 'low', // Notice / 通知
+    6: 'info', // Informational / 資訊
+    7: 'info', // Debug / 除錯
+};
+/**
+ * RFC 5424 syslog facility names
+ * RFC 5424 syslog 設施名稱
+ */
+const SYSLOG_FACILITY_NAMES = {
+    0: 'kern',
+    1: 'user',
+    2: 'mail',
+    3: 'daemon',
+    4: 'auth',
+    5: 'syslog',
+    6: 'lpr',
+    7: 'news',
+    8: 'uucp',
+    9: 'cron',
+    10: 'authpriv',
+    11: 'ftp',
+    12: 'ntp',
+    13: 'security',
+    14: 'console',
+    15: 'solaris-cron',
+    16: 'local0',
+    17: 'local1',
+    18: 'local2',
+    19: 'local3',
+    20: 'local4',
+    21: 'local5',
+    22: 'local6',
+    23: 'local7',
+};
+/**
+ * Regular expression for parsing RFC 5424 syslog messages
+ * 用於解析 RFC 5424 syslog 訊息的正則表達式
+ *
+ * RFC 5424 format:
+ * <PRI>VERSION SP TIMESTAMP SP HOSTNAME SP APP-NAME SP PROCID SP MSGID SP STRUCTURED-DATA [SP MSG]
+ *
+ * Where PRI = facility * 8 + severity
+ */
+const RFC5424_REGEX = /^<(\d{1,3})>(\d+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+((?:\[.*?\])+|-)\s*(.*)?$/s;
+/**
+ * Parse a raw syslog message string into structured fields
+ * 將原始 syslog 訊息字串解析為結構化欄位
+ *
+ * Supports RFC 5424 format. Falls back to a best-effort parse for
+ * non-conforming messages by treating the entire string as the message body.
+ * 支援 RFC 5424 格式。對於不符合格式的訊息，會以盡力解析方式
+ * 將整個字串視為訊息本體。
+ *
+ * @param raw - Raw syslog message string / 原始 syslog 訊息字串
+ * @returns Parsed syslog message fields / 已解析的 syslog 訊息欄位
+ */
+export function parseSyslogMessage(raw) {
+    const match = RFC5424_REGEX.exec(raw.trim());
+    if (!match) {
+        // Attempt basic PRI extraction for BSD-style (RFC 3164) messages
+        // 嘗試對 BSD 風格 (RFC 3164) 訊息進行基本 PRI 擷取
+        const priMatch = /^<(\d{1,3})>(.*)$/s.exec(raw.trim());
+        if (priMatch) {
+            const pri = parseInt(priMatch[1] ?? '0', 10);
+            const facility = Math.floor(pri / 8);
+            const severityCode = pri % 8;
+            return {
+                facility,
+                severityCode,
+                version: 0,
+                timestamp: new Date().toISOString(),
+                hostname: '-',
+                appName: '-',
+                procId: '-',
+                msgId: '-',
+                structuredData: '-',
+                message: (priMatch[2] ?? '').trim(),
+            };
+        }
+        // Completely unparseable - treat as info-level user message
+        // 完全無法解析 - 視為資訊等級的使用者訊息
+        return {
+            facility: 1,
+            severityCode: 6,
+            version: 0,
+            timestamp: new Date().toISOString(),
+            hostname: '-',
+            appName: '-',
+            procId: '-',
+            msgId: '-',
+            structuredData: '-',
+            message: raw.trim(),
+        };
+    }
+    const pri = parseInt(match[1] ?? '0', 10);
+    const facility = Math.floor(pri / 8);
+    const severityCode = pri % 8;
+    const m3 = match[3] ?? '';
+    const m4 = match[4] ?? '';
+    const m5 = match[5] ?? '';
+    const m6 = match[6] ?? '';
+    const m7 = match[7] ?? '';
+    const m8 = match[8] ?? '';
+    return {
+        facility,
+        severityCode,
+        version: parseInt(match[2] ?? '0', 10),
+        timestamp: m3 === '-' ? new Date().toISOString() : m3,
+        hostname: m4 === '-' ? '' : m4,
+        appName: m5 === '-' ? '' : m5,
+        procId: m6 === '-' ? '' : m6,
+        msgId: m7 === '-' ? '' : m7,
+        structuredData: m8 === '-' ? '' : m8,
+        message: (match[9] ?? '').trim(),
+    };
+}
+/**
+ * Convert a parsed syslog message to an AdapterAlert
+ * 將已解析的 syslog 訊息轉換為 AdapterAlert
+ *
+ * @param parsed - Parsed syslog message / 已解析的 syslog 訊息
+ * @param raw - Original raw message string / 原始訊息字串
+ * @returns AdapterAlert instance / AdapterAlert 實例
+ */
+function toAdapterAlert(parsed, raw) {
+    const facilityName = SYSLOG_FACILITY_NAMES[parsed.facility] ?? `facility-${parsed.facility}`;
+    const severityString = SYSLOG_SEVERITY_MAP[parsed.severityCode] ?? 'info';
+    return {
+        id: randomUUID(),
+        timestamp: parsed.timestamp,
+        severity: severityString,
+        title: `[${facilityName}] ${parsed.appName || 'syslog'}: ${parsed.msgId || 'message'}`,
+        description: parsed.message || raw,
+        source: 'syslog',
+        raw: {
+            parsed,
+            original: raw,
+        },
+    };
+}
+/**
+ * Syslog receiver security adapter (RFC 5424)
+ * Syslog 接收器安全對接器 (RFC 5424)
+ *
+ * Listens for syslog messages on a UDP socket, parses RFC 5424 format,
+ * buffers parsed alerts, and provides both callback-based real-time
+ * notification and pull-based alert retrieval.
+ *
+ * 在 UDP socket 上監聽 syslog 訊息，解析 RFC 5424 格式，
+ * 緩衝已解析的告警，並提供基於回呼的即時通知和拉取式告警取得。
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SyslogAdapter({ enabled: true });
+ *
+ * // Set up real-time callback / 設定即時回呼
+ * adapter.onAlert((alert) => {
+ *   console.log('New syslog alert:', alert);
+ * });
+ *
+ * // Start listening on port 514 / 開始在埠 514 上監聽
+ * await adapter.start(514);
+ *
+ * // Later: retrieve buffered alerts / 稍後：取得緩衝的告警
+ * const alerts = await adapter.getAlerts();
+ *
+ * // Stop listening / 停止監聽
+ * adapter.stop();
+ * ```
+ */
+export class SyslogAdapter extends BaseAdapter {
+    /** @inheritdoc */
+    name = 'Syslog Receiver';
+    /** @inheritdoc */
+    type = 'syslog';
+    /**
+     * UDP socket for receiving syslog messages
+     * 用於接收 syslog 訊息的 UDP socket
+     */
+    socket = null;
+    /**
+     * Buffer of alerts received since last getAlerts() call
+     * 自上次 getAlerts() 呼叫以來接收的告警緩衝區
+     */
+    alertBuffer = [];
+    /**
+     * Real-time alert callback
+     * 即時告警回呼
+     */
+    alertCallback = null;
+    /**
+     * Whether the socket is currently listening
+     * socket 是否正在監聽
+     */
+    listening = false;
+    /**
+     * Port the socket is listening on
+     * socket 正在監聽的埠
+     */
+    listenPort = 0;
+    /**
+     * Create a new SyslogAdapter instance
+     * 建立新的 SyslogAdapter 實例
+     *
+     * @param config - Adapter configuration / 對接器配置
+     */
+    constructor(config = { enabled: true }) {
+        super('adapter-syslog', config);
+    }
+    /**
+     * Register a callback for real-time alert notification
+     * 註冊即時告警通知的回呼
+     *
+     * The callback is invoked for each parsed syslog message as it arrives.
+     * Only one callback can be registered at a time; setting a new one
+     * replaces the previous.
+     * 每收到一筆已解析的 syslog 訊息就會呼叫此回呼。
+     * 同一時間只能註冊一個回呼；設定新的會取代前一個。
+     *
+     * @param callback - Alert callback function / 告警回呼函式
+     */
+    onAlert(callback) {
+        this.alertCallback = callback;
+    }
+    /**
+     * Check if the syslog receiver is available (i.e. listening)
+     * 檢查 syslog 接收器是否可用（即正在監聽）
+     *
+     * @returns True if the UDP socket is bound and listening / 若 UDP socket 已綁定且正在監聽則回傳 true
+     */
+    async isAvailable() {
+        return this.listening;
+    }
+    /**
+     * Start the UDP syslog receiver
+     * 啟動 UDP syslog 接收器
+     *
+     * Binds a UDP4 socket to the specified port and begins listening
+     * for incoming syslog messages. Each message is parsed according to
+     * RFC 5424 and added to the alert buffer.
+     * 將 UDP4 socket 綁定到指定埠並開始監聽傳入的 syslog 訊息。
+     * 每筆訊息都會依 RFC 5424 解析並新增到告警緩衝區。
+     *
+     * @param port - UDP port to listen on (default: 514) / 要監聽的 UDP 埠（預設：514）
+     * @returns Promise that resolves when the socket is bound / socket 綁定後 resolve 的 Promise
+     */
+    start(port = DEFAULT_SYSLOG_PORT) {
+        return new Promise((resolve, reject) => {
+            if (this.listening) {
+                this.logger.warn('Syslog receiver is already listening', { port: this.listenPort });
+                resolve();
+                return;
+            }
+            this.socket = dgram.createSocket('udp4');
+            this.socket.on('message', (msg, rinfo) => {
+                try {
+                    const raw = msg.toString('utf8');
+                    const parsed = parseSyslogMessage(raw);
+                    const alert = toAdapterAlert(parsed, raw);
+                    // Add source IP to alert metadata / 新增來源 IP 到告警中繼資料
+                    alert.raw['remoteAddress'] = rinfo.address;
+                    alert.raw['remotePort'] = rinfo.port;
+                    // Buffer the alert / 緩衝告警
+                    this.alertBuffer.push(alert);
+                    // Enforce buffer size limit / 強制緩衝區大小限制
+                    if (this.alertBuffer.length > MAX_BUFFER_SIZE) {
+                        const discarded = this.alertBuffer.length - MAX_BUFFER_SIZE;
+                        this.alertBuffer = this.alertBuffer.slice(discarded);
+                        this.logger.warn(`Alert buffer overflow, discarded ${discarded} oldest alerts`);
+                    }
+                    // Invoke real-time callback if registered / 若已註冊則呼叫即時回呼
+                    if (this.alertCallback) {
+                        this.alertCallback(alert);
+                    }
+                    this.logger.debug('Parsed syslog message', {
+                        from: `${rinfo.address}:${rinfo.port}`,
+                        facility: parsed.facility,
+                        severity: parsed.severityCode,
+                        hostname: parsed.hostname,
+                        appName: parsed.appName,
+                    });
+                }
+                catch (err) {
+                    this.logger.error('Failed to parse syslog message', {
+                        from: `${rinfo.address}:${rinfo.port}`,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            });
+            this.socket.on('error', (err) => {
+                this.logger.error('Syslog socket error', { error: err.message });
+                if (!this.listening) {
+                    // Error during binding / 綁定期間的錯誤
+                    reject(err);
+                }
+            });
+            this.socket.on('close', () => {
+                this.listening = false;
+                this.listenPort = 0;
+                this.logger.info('Syslog socket closed');
+            });
+            this.socket.bind(port, () => {
+                this.listening = true;
+                this.listenPort = port;
+                const address = this.socket?.address();
+                this.logger.info('Syslog receiver started', {
+                    port: address?.port ?? port,
+                    address: address?.address ?? '0.0.0.0',
+                });
+                resolve();
+            });
+        });
+    }
+    /**
+     * Stop the UDP syslog receiver
+     * 停止 UDP syslog 接收器
+     *
+     * Closes the UDP socket and stops listening for messages.
+     * The alert buffer is preserved and can still be read via getAlerts().
+     * 關閉 UDP socket 並停止監聽訊息。
+     * 告警緩衝區會被保留，仍可透過 getAlerts() 讀取。
+     */
+    stop() {
+        if (this.socket) {
+            try {
+                this.socket.close();
+            }
+            catch {
+                // Socket may already be closed / Socket 可能已經關閉
+            }
+            this.socket = null;
+        }
+        this.listening = false;
+        this.listenPort = 0;
+        this.logger.info('Syslog receiver stopped');
+    }
+    /**
+     * Retrieve buffered alerts and clear the buffer
+     * 取得緩衝的告警並清除緩衝區
+     *
+     * Returns all alerts accumulated since the last call to getAlerts().
+     * Optionally filters by a cutoff date. The buffer is cleared after
+     * retrieval to prevent duplicate processing.
+     * 回傳自上次呼叫 getAlerts() 以來累積的所有告警。
+     * 可選依截止日期過濾。取得後會清除緩衝區以防止重複處理。
+     *
+     * @param since - Optional cutoff date / 可選截止日期
+     * @returns Array of buffered adapter alerts / 緩衝的對接器告警陣列
+     */
+    async getAlerts(since) {
+        // Drain the buffer / 排空緩衝區
+        const buffered = this.alertBuffer.splice(0, this.alertBuffer.length);
+        if (!since) {
+            this.logger.debug(`Returning ${buffered.length} buffered syslog alerts`);
+            return buffered;
+        }
+        // Filter by cutoff date / 依截止日期過濾
+        const filtered = buffered.filter((alert) => {
+            const alertTime = new Date(alert.timestamp);
+            return alertTime >= since;
+        });
+        this.logger.debug(`Returning ${filtered.length} syslog alerts (${buffered.length} total buffered)`, {
+            since: since.toISOString(),
+        });
+        return filtered;
+    }
+    /**
+     * Get the current buffer size (number of pending alerts)
+     * 取得目前緩衝區大小（待處理告警數量）
+     *
+     * @returns Number of alerts in the buffer / 緩衝區中的告警數量
+     */
+    getBufferSize() {
+        return this.alertBuffer.length;
+    }
+    /**
+     * Check if the receiver is currently listening
+     * 檢查接收器是否正在監聽
+     *
+     * @returns True if listening / 若正在監聽則回傳 true
+     */
+    isListening() {
+        return this.listening;
+    }
+    /**
+     * Get the port the receiver is listening on
+     * 取得接收器正在監聽的埠
+     *
+     * @returns Port number, or 0 if not listening / 埠號，若未監聽則為 0
+     */
+    getPort() {
+        return this.listenPort;
+    }
+}
+//# sourceMappingURL=syslog-adapter.js.map

package/dist/adapters/syslog-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syslog-adapter.js","sourceRoot":"","sources":["../../src/adapters/syslog-adapter.ts"],"names":[],"mappings":"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"}