# Описание компонента zh_syslog

## Общие сведения

**zh_syslog** — это лёгкий UDP-клиент syslog для ESP-IDF, отправляющий сообщения на удалённый syslog-сервер в формате [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424).

Компонент оборачивает стандартный BSD-сокет UDP и предоставляет несколько функций для инициализации, отправки сообщений и освобождения ресурсов.

## Основные возможности

1. **Все коды facility (0–23)** — поддержка стандартных значений по RFC 5424, включая `LOCAL0`–`LOCAL7` для локального использования.
2. **Все уровни severity (0–7)** — от `ZH_EMERG` до `ZH_DEBUG`.
3. **Формат RFC 5424** — автоматический расчёт приоритета `<PRI>` и генерация заголовка сообщения.
4. **Отправка по UDP** — сокеты не устанавливают соединения, сообщения доставляются дейтаграммами.
5. **Двухуровневая работа с памятью** — короткие сообщения форматируются в стековом буфере, длинные аллоцируются в куче точным размером.
6. **Проверка входных аргументов** — валидация IP-адреса, порта и диапазона кодов на этапе вызова.
7. **Потокобезопасные `init`/`deinit`** — защита состояния флагом инициализации (см. раздел «Ограничения» для `send`).

## Внутреннее устройство

### Структура `zh_syslog_init_config_t`

Публичная конфигурационная структура, передаваемая в `zh_syslog_init()`.

| Поле | Тип | Описание |
|------|-----|----------|
| `syslog_ip` | `char[16]` | IPv4-адрес syslog-сервера в виде строки (макс. 15 символов + `'\0'`) |
| `syslog_port` | `uint32_t` | UDP-порт сервера (диапазон 1–65535, по умолчанию 514) |

Для заполнения значений по умолчанию используется макрос `ZH_SYSLOG_INIT_CONFIG_DEFAULT()` (IP `192.168.0.1`, порт `514`).

### Внутренние переменные модуля

Не входят в публичный API и хранятся как `static` в `zh_syslog.c`.

| Переменная | Тип | Описание |
|------------|-----|----------|
| `_syslog_server` | `struct sockaddr_in` | Адрес сервера: IPv4, порт в сетевом порядке, семья `AF_INET` |
| `_socket` | `volatile int` | Дескриптор UDP-сокета, `-1` когда клиент не инициализирован |
| `_is_initialized` | `volatile bool` | Флаг состояния: `true` после успешного `init` |

Флаг `_is_initialized` используется как простой сторож состояния: `init` отказывает при уже инициализированном клиенте, `deinit` и `send` отказывают при неинициализированном.

### Управление памятью

- Короткое сообщение (помещающееся в стековый буфер `char stack_buf[256]`) форматируется прямо в стеке — аллокации в куче не происходит.
- Если `snprintf` вернул `len >= 256` (строка обрезана), память выделяется в куче ровно под `len + 1` байт через `heap_caps_calloc(..., MALLOC_CAP_8BIT)`.
- Флаг `heap_allocated` отслеживает, нужно ли освобождать буфер: `heap_caps_free()` вызывается владением только для кучного буфера — и при успехе, и при ошибке форматирования.

## API (интерфейс)

### Инициализация и освобождение

| Функция | Описание |
|---------|----------|
| `zh_syslog_init()` | Создаёт UDP-сокет и настраивает параметры соединения с сервером. |
| `zh_syslog_deinit()` | Закрывает сокет и сбрасывает состояние клиента. |

### Отправка сообщений

| Функция | Описание |
|---------|----------|
| `zh_syslog_send()` | Форматирует сообщение по RFC 5424 и отправляет его на настроенный сервер. |

### Типы и значения

| Элемент | Описание |
|---------|----------|
| `zh_syslog_facility_code_t` | Перечисление кодов facility `ZH_KERN`…`ZH_LOCAL7` (0–23). |
| `zh_syslog_severity_code_t` | Перечисление уровней severity `ZH_EMERG`…`ZH_DEBUG` (0–7). |
| `zh_syslog_init_config_t` | Структура конфигурации (IP и порт сервера). |
| `ZH_SYSLOG_INIT_CONFIG_DEFAULT()` | Макрос значений конфигурации по умолчанию. |

## Потокобезопасность

1. **Флаг состояния `_is_initialized`** — `volatile bool`, используется как сторож в `init`/`deinit`/`send` для защиты от повторной инициализации и от работы без инициализации.
2. **Дескриптор сокета `_socket`** — `volatile int`, обновляется при `init`/`deinit`.

Мьютексы и критические секции не используются. Проверка флага и последующая работа с сокетом не образуют атомарной операции, поэтому `zh_syslog_send()` **не является потокобезопасной** — подробности в разделе «Ограничения».

## Алгоритмы

### Расчёт приоритета

- Приоритет `<PRI>` считается по формуле RFC 5424: `pri = facility * 8 + severity`.
- Значение подставляется в начало сообщения в угловых скобках: `<%d>1 - ...`.

### Формат сообщения

Шаблон генерируемого сообщения:

```
<PRI>1 - HOSTNAME APP-NAME - - - MESSAGE
```

Поля `PROCID`, `MSGID` и `STRUCTURED-DATA` не заполняются и заменяются на `-` согласно RFC 5424.

### Выбор буфера под размер сообщения

- Сообщение форматируется в стековый буфер `stack_buf[256]` через `snprintf`, который возвращает полную длину строки.
- Если возвращённая длина меньше размера буфера — сокету передаётся стековый буфер.
- Если длина `>= 256` — выделяется кучный буфер точного размера `len + 1`, сообщение форматируется повторно и отправляется, после чего буфер освобождается.

## Примеры использования

### Базовый пример

```c
#include "zh_syslog.h"

void app_main(void)
{
    // Сеть (Wi-Fi/Ethernet) должна быть поднята до init
    zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
    strcpy(config.syslog_ip, "192.168.1.100");
    config.syslog_port = 514;

    if (zh_syslog_init(&config) == ESP_OK)
    {
        // Отправка сообщения с приоритетом USER/INFO
        zh_syslog_send(ZH_USER, ZH_INFO, "esp32_node", "my_app", "Hello syslog");
    }

    // Освобождение ресурсов
    zh_syslog_deinit();
}
```

### Работа с разными уровнями и facility

```c
#include "zh_syslog.h"

void log_events(void)
{
    zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
    strcpy(config.syslog_ip, "10.0.0.5");
    zh_syslog_init(&config);

    // Разные facility и severity для разных событий
    zh_syslog_send(ZH_KERN,     ZH_ERR,     "dev1", "fw",   "kernel error");
    zh_syslog_send(ZH_LOCAL0,   ZH_WARNING, "dev1", "fw",   "sensor timeout");
    zh_syslog_send(ZH_DAEMON,   ZH_DEBUG,   "dev1", "fw",   "loop tick");

    zh_syslog_deinit();
}
```

### Отправка длинного сообщения

```c
#include "zh_syslog.h"

void send_long_message(void)
{
    zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT();
    strcpy(config.syslog_ip, "10.0.0.5");
    zh_syslog_init(&config);

    // Сообщение длиннее стекового буфера уходит через кучу
    char big[512];
    memset(big, 'A', sizeof(big) - 1);
    big[sizeof(big) - 1] = '\0';
    zh_syslog_send(ZH_USER, ZH_INFO, "dev1", "app", big);

    zh_syslog_deinit();
}
```

## Логирование

Компонент использует ESP-IDF логирование с тегом `"zh_syslog"`.

```c
esp_log_level_set("zh_syslog", ESP_LOG_ERROR);
```

Ошибки логируются с указанием файла, строки и имени кода ошибки (`esp_err_to_name`).

## Ошибки

| Код | Описание |
|-----|----------|
| `ESP_OK` | Успех |
| `ESP_ERR_INVALID_ARG` | Неверный аргумент: `NULL`-указатель, порт вне диапазона, некорректный IP или код вне диапазона |
| `ESP_ERR_INVALID_STATE` | Клиент уже инициализирован (`init`) либо ещё не инициализирован (`deinit`/`send`) |
| `ESP_ERR_NO_MEM` | Не удалось выделить память под длинное сообщение |
| `ESP_FAIL` | Ошибка создания сокета, форматирования или отправки UDP |

## Ограничения

1. **`zh_syslog_send()` не потокобезопасна** — проверка флага и работа с сокетом не атомарны; при конкурентном вызове из нескольких задач нужна внешняя синхронизация.
2. **Только IPv4** — адрес сервера задаётся строкой и разбирается через `inet_pton(AF_INET, ...)`, IPv6 не поддерживается.
3. **Без гарантии доставки** — UDP не подтверждает доставку, потерю сообщений компонент не отслеживает.
4. **Длина IP ограничена 15 символами** — поле `syslog_ip[16]` вмещает только IPv4-строку.
5. **Требуется активная сеть** — вызывать `zh_syslog_init()` можно только после установления сетевого соединения.
6. **Стек 256 байт на сообщение** — сообщения длиннее буфера приводят к аллокации в куче на каждую отправку.

## Требования для сборки

- ESP-IDF версии 5.0 и выше.
- FreeRTOS (входит в состав ESP-IDF).
- lwIP (стек сокетов, входит в состав ESP-IDF).

## Установка

```bash
cd ваш_проект/components
git clone https://github.com/aZholtikov/zh_syslog
```

```c
#include "zh_syslog.h"
```