ClickHouse/dbms/include/DB/Core/Protocol.h

#pragma once

#include <DB/Core/Types.h>


namespace DB
{

/** Протокол взаимодействия с сервером.
  *
  * Клиент соединяется с сервером и передаёт ему пакет Hello.
  * Если версия не устраивает, то сервер может разорвать соединение.
  * Сервер отвечает пакетом Hello.
  * Если версия не устраивает, то клиент может разорвать соединение.
  *
  * Далее в цикле.
  *
  * 1. Клиент отправляет на сервер пакет Query.
  *
  * Начиная с версии 50263, сразу после отправки пакета Query клиент начинает передачу
  *  внешних (временных) таблиц (external storages) - один или несколько пакетов Data.
  * Конец передачи данных определается по отправленному пустому блоку.
  * В данный момент, не пустое множество таблиц может быть передано только вместе с запросом SELECT.
  *
  * Если запрос типа INSERT (требует передачи данных от клиента), то сервер передаёт
  *  пакет Data, содержащий пустой блок, который описывает структуру таблицы.
  * Затем клиент отправляет данные для вставки
  * - один или несколько пакетов Data.
  * Конец данных определается по отправленному пустому блоку.
  * Затем сервер отправляет клиенту пакет EndOfStream.
  *
  * Если запрос типа SELECT или другой, то сервер передаёт набор пакетов одного из следующих видов:
  * - Data - данные результата выполнения запроса (один блок);
  * - Progress - прогресс выполнения запроса;
  * - Exception - ошибка;
  * - EndOfStream - конец передачи данных;
  *
  * Клиент должен читать пакеты до EndOfStream или Exception.
  * Также, клиент может передать на сервер пакет Cancel - отмена выполнения запроса.
  * В этом случае, сервер может прервать выполнение запроса и вернуть неполные данные;
  *  но клиент всё равно должен читать все пакеты до EndOfStream.
  *
  * Перед пакетом EndOfStream, если есть профайлинговая информация и ревизия клиента достаточно новая,
  * может быть отправлен пакет Totals и/или ProfileInfo.
  * Totals - блок с тотальными значениями.
  * ProfileInfo - данные профайлинга - сериализованная структура BlockStreamProfileInfo.
  *
  * При запросах, которые возвращают данные, сервер, перед обработкой запроса,
  * отправляет заголовочный блок, содержащий описание столбцов из запроса, но с нулем строк.
  * Используя этот заголовочный блок, клиент может заранее проинициализировать формат вывода
  * и вывести префикс таблицы результата.
  *
  * 2. Между запросами, клиент может отправить Ping, и сервер должен ответить Pong.
  */

namespace Protocol
{
    /// То, что передаёт сервер.
    namespace Server
    {
        enum Enum
        {
            Hello = 0,            /// Имя, версия, ревизия.
            Data = 1,            /// Блок данных со сжатием или без.
            Exception = 2,        /// Исключение во время обработки запроса.
            Progress = 3,        /// Прогресс выполнения запроса: строк считано, байт считано.
            Pong = 4,            /// Ответ на Ping.
            EndOfStream = 5,    /// Все пакеты были переданы.
            ProfileInfo = 6,    /// Пакет с профайлинговой информацией.
            Totals = 7,            /// Блок данных с тотальными значениями, со сжатием или без.
            Extremes = 8,        /// Блок данных с минимумами и максимумами, аналогично.
        };

        /** NOTE: Если бы в качестве типа агрумента функции был бы Enum, то сравнение packet >= 0 && packet < 7
          * срабатывало бы всегда из-за оптимизации компилятором, даже если packet некорректный, и было бы чтение за границей массива.
          * https://www.securecoding.cert.org/confluence/display/cplusplus/INT36-CPP.+Do+not+use+out-of-range+enumeration+values
          */
        inline const char * toString(UInt64 packet)
        {
            static const char * data[] = { "Hello", "Data", "Exception", "Progress", "Pong", "EndOfStream", "ProfileInfo", "Totals", "Extremes" };
            return packet < 9
                ? data[packet]
                : "Unknown packet";
        }
    }

    /// То, что передаёт клиент.
    namespace Client
    {
        enum Enum
        {
            Hello = 0,            /// Имя, версия, ревизия, БД по-умолчанию.
            Query = 1,            /** Идентификатор запроса, настройки на отдельный запрос,
                                  * информация, до какой стадии исполнять запрос,
                                  * использовать ли сжатие, текст запроса (без данных для INSERT-а).
                                  */
            Data = 2,            /// Блок данных со сжатием или без.
            Cancel = 3,            /// Отменить выполнение запроса.
            Ping = 4,            /// Проверка живости соединения с сервером.
        };

        inline const char * toString(UInt64 packet)
        {
            static const char * data[] = { "Hello", "Query", "Data", "Cancel", "Ping" };
            return packet < 5
                ? data[packet]
                : "Unknown packet";
        }
    }

    /// Использовать ли сжатие.
    namespace Compression
    {
        enum Enum
        {
            Disable = 0,
            Enable = 1,
        };
    }
}

}