# tgloggerd

tgloggerd is a Telegram logger daemon that runs on a regular user
account. It is built on top of TDLib and keeps its data in MySQL 9. It
records user messages, message edit history, and profile changes such
as usernames, names, and photos. For groups it also tracks the
administrator list and each admin's privileges, keeping a history of
admin changes. Since a regular user account is not pushed admin changes,
the admin list is fetched when a group is first seen and refreshed by
periodic polling (see TG_ADMIN_POLL_INTERVAL in run.example.sh).

# Project structure

    src/                       Main tgloggerd source code.
      main.c                   Entry point; reads configuration from the
                               environment and starts the daemon.
      log.c, log.h             Small logging helper (pr_info, pr_err, ...).
      mysql/                   Generic MySQL layer (no tgloggerd specifics):
        ConnectionPool.{hpp,cpp}  Thread-safe pool of JDBC connections.
        Database.{hpp,cpp}        Prepared-statement executor over the pool.
      tgloggerd/               The tgloggerd application code:
        TgLoggerd.{hpp,cpp}       Main class; wires TDLib to the database.
        TDLib.{hpp,cpp}           Thin wrapper around TDLib (see below).
        DB.{hpp,cpp}              DB class lifecycle and facade interface.
        tgloggerd_extern.{h,cpp}  C ABI used by main.c.
        helpers/                  C helpers (logging, filesystem).
        models/                   Data models (.hpp) and their SQL query
                                  implementations (.cpp) (User, File, ...).
    migrations/                golang-migrate SQL migrations for the schema.
    submodules/                Third-party dependencies vendored as git
                               submodules: TDLib (td) and MySQL
                               Connector/C++ (mysql-connector-cpp).
    data/                      Runtime data (git-ignored contents):
      users/                     Per-account TDLib data directories.
      mysql/                     MySQL server data (docker volume).
      storage/files/             Downloaded files, named by SHA-256.
    docker-compose.example.yml Example MySQL service definition.
    run.example.sh             Example run script; copy to run.sh.

# Interaction with TDLib

TDLib ships very large headers that noticeably slow tgloggerd's
compilation, so the code that touches TDLib is kept to a minimum. All
direct TDLib usage lives in src/tgloggerd/TDLib.cpp, which exposes a
small wrapper (tgloggerd::TDLib) through TDLib.hpp.

# Prerequisites

Install the following before building:

  - git (with submodule support).
  - A C/C++ toolchain (gcc/g++ or clang) with C11 and C++17 support.
  - CMake 3.16 or newer.
  - TDLib build dependencies: OpenSSL, zlib, and gperf.
  - Docker with the Docker Compose plugin to run MySQL 9, or an
    existing MySQL 9 server.
  - golang-migrate to apply the database migrations.

On Debian/Ubuntu the build dependencies can be installed with:

    sudo apt install git build-essential cmake gperf libssl-dev zlib1g-dev

Install golang-migrate with the Go toolchain (the "mysql" build tag
enables the MySQL driver):

    go install -tags 'mysql' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

Prebuilt golang-migrate binaries are also available at
https://github.com/golang-migrate/migrate/releases.

# Building

Fetch the submodules (TDLib and MySQL Connector/C++), then configure and
build:

    git submodule update --init --recursive
    cmake -B build
    cmake --build build -j"$(nproc)"

The first build compiles TDLib from source and may take a while.

The vendored MySQL Connector/C++ builds its own copy of protobuf, whose
CMakeLists still declares a cmake_minimum_required below 3.5. CMake 4.0
and newer reject this and the configure step fails with:

    Compatibility with CMake < 3.5 has been removed from CMake.

If you are on CMake 4 or newer, set CMAKE_POLICY_VERSION_MINIMUM to 3.5.
Export it (not just -D) so it also reaches protobuf's separate external
build:

    export CMAKE_POLICY_VERSION_MINIMUM=3.5
    cmake -B build -DCMAKE_POLICY_VERSION_MINIMUM=3.5
    cmake --build build -j"$(nproc)"

# Running

1. Start MySQL. Copy the example Compose file, adjust the credentials if
   needed, and bring the service up:

       cp docker-compose.example.yml docker-compose.yml
       docker compose up -d mysql

2. Apply the database migrations. Point golang-migrate at the running
   MySQL instance, matching the host, port, and credentials in your
   docker-compose.yml:

       migrate -path migrations \
           -database "mysql://tgloggerd:tgloggerd@tcp(10.0.88.3:3306)/tgloggerd" up

3. Copy the example run script to run.sh and edit it with your own
   credentials. run.sh is intentionally not committed because it holds
   your API credentials:

       cp run.example.sh run.sh
       # edit run.sh: set TG_API_ID and TG_API_HASH (from
       # https://my.telegram.org) and adjust TG_DATA_DIR as needed

   Then run it:

       ./run.sh

On the first run, tgloggerd prompts on stdin for your phone number, the
login code, and your password (if two-step verification is enabled).