# tdlib_ping — официальный JSON-интерфейс TDLib

Бинарник вызывает **`td_create_client_id` / `td_send` / `td_receive` / `td_execute`** из [`td/telegram/td_json_client.h`](https://github.com/tdlib/td/blob/master/td/telegram/td_json_client.h) (рекомендуемый multi-client API), без Node.js.

Контракт stdout — одна строка JSON для `mtproxy_checkerd`:

`{"ok":true,"error":"","exit_code":0}`

## Сборка в CI (Gitea)

В репозитории есть workflow **`.gitea/workflows/tdlib_ping.yaml`** (те же триггеры, что и у публикации Docker: push по **любой ветке** и **любому тегу**, плюс `workflow_dispatch`). **TDLib собирается из исходников** (тег задаётся в workflow, переменная `TDLIB_REF`), пакета `libtdjson-dev` в apt не требуется.

В релиз и в артефакты попадает архив **`tdlib_ping-linux-amd64.tar.gz`**: внутри бинарник **`tdlib_ping-linux-amd64`** и **`libtdjson.so*`** с `rpath=$ORIGIN` (всё в одной папке после распаковки).

```bash
mkdir -p /opt/tdlib-ping && tar -xzf tdlib_ping-linux-amd64.tar.gz -C /opt/tdlib-ping
chmod +x /opt/tdlib-ping/tdlib_ping-linux-amd64
export MTPROXY_TDLIB_HELPER=/opt/tdlib-ping/tdlib_ping-linux-amd64
```

При push **тега** архив прикрепляется к **релизу** (релиз создаётся при отсутствии); при push **ветки** или `workflow_dispatch` — только артефакт прогона в Actions (для Gitea используется `upload-artifact@v3`, не v4).

## Сборка

Linux (Debian/Ubuntu), установите заголовки и библиотеку, например:

**Важно:** в **Ubuntu 24.04 (Noble)** и на части окружений **Jammy** пакета **`libtdjson-dev` в apt может не быть**. Тогда [соберите TDLib из исходников](https://github.com/tdlib/td#building) или возьмите готовый **`tdlib_ping-linux-amd64.tar.gz`** из CI (см. выше).

```bash
sudo apt-get install -y libtdjson-dev   # если пакет есть в вашем дистрибутиве
export CGO_ENABLED=1
go build -tags=tdlib -o tdlib_ping ./cmd/tdlib_ping
```

Если TDLib собран из [git](https://github.com/tdlib/td): заголовок подключается как `#include <td/telegram/td_json_client.h>`, поэтому **`CGO_CFLAGS` должен указывать на корень клона** (каталог, внутри которого лежит `td/telegram/…`), а не на вложенный `td/`:

```bash
export CGO_ENABLED=1
# Корень клона + каталог cmake build (там tdjson_export.h после target tdjson).
export CGO_CFLAGS="-I/path/to/td-clone -I/path/to/td-clone/build"
export CGO_LDFLAGS="-L/path/to/td-clone/build -ltdjson"
go build -tags=tdlib -o tdlib_ping ./cmd/tdlib_ping
```

macOS: `brew install tdlib`, затем при необходимости `export PKG_CONFIG_PATH=...` если `pkg-config --libs tdlib` находит `-ltdjson`.

Без `libtdjson` линковка завершится ошибкой — это ожидаемо.

Сборка **без** тега (как часть `go build ./...`):

```bash
go build ./cmd/tdlib_ping
```

получится заглушка, которая печатает JSON с `exit_code: 2` и пояснением — чтобы репозиторий собирался без TDLib.

## Переменные окружения

| Переменная | По умолчанию | Назначение |
|------------|--------------|------------|
| `MTPROXY_TD_API_ID` | `12345` | Замените на значение с [my.telegram.org](https://my.telegram.org) |
| `MTPROXY_TD_API_HASH` | демо-строка из примера TDLib | Замените на свой `api_hash` |
| `MTPROXY_TDLIB_PING_MS` | `45000` | Общий дедлайн цикла (мс) |
| `MTPROXY_TDLIB_DATABASE_DIR` | пусто | Если задан — постоянный каталог для `database_directory` / `files_directory` (подкаталоги `db/` и `files/` создаются автоматически). Иначе — временный каталог на каждый запуск |
| `MTPROXY_TD_USE_TEST_DC` | пусто | Если `1` — `use_test_dc: true` в `setTdlibParameters` (иногда помогает обойти ожидание телефона на «чистой» БД) |

## Запуск

```bash
./tdlib_ping 'tg://proxy?server=HOST&port=PORT&secret=HEX'
```

Если **`MTPROXY_TDLIB_DATABASE_DIR`** не задан, каталоги БД TDLib создаются под уникальным префиксом во временном каталоге на каждый запуск (и удаляются после выхода).

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

При первом запуске с «чистой» БД TDLib может перейти в **`authorizationStateWaitPhoneNumber`**. Тогда helper завершится с ошибкой в JSON — нужен уже проинициализированный `database_directory` или рабочий сценарий входа. Для типичного мониторинга MTProxy на выделенной машине обычно достаточно повторных запусков с фиксированным каталогом (`MTPROXY_TDLIB_DATABASE_DIR`, см. таблицу выше).