h12_library.md

Интерфейс библиотеки для работы с HTTP 1, 2

• Типы данных
  • logger
  • logger_log_level
  • http_session
  • http1_session
  • http2_session
  • http_stream
  • http_session_type
• Функции
  • logger_open
  • logger_log
  • logger_close
  • http_session_init
  • http_session_input_settings
  • http_session_input
  • http_session_close
• Коллбэки
  • h1_headers
  • h1_data_started
  • h1_data
  • h1_data_finished
  • h2_frame
  • h2_headers
  • h2_data_started
  • h2_data
  • h2_data_finished
  • output
• Вспомогательные методы

Типы данных

logger

Контекст логгера

typedef struct logger {
    FILE *file;
    logger_callback callback; 
    logger_log_level level;
    void *attachment;
} logger;

• file Указатель на структуру FILE открытого логфайла
• callback Указатель на коллбэк (если он ненулевой, то file не используется)
• level Уровень логгирования

logger_log_level

Уровень логгирования

enum logger_log_level {
    LOG_LEVEL_ERROR = 0,
    LOG_LEVEL_WARN,
    LOG_LEVEL_INFO,
    LOG_LEVEL_DEBUG,
    LOG_LEVEL_TRACE
};

Уровни соответствуют общепринятым.

http_session

Контекст HTTP-парсера

struct http_session {
    void *attachment;
    union {
        struct http1_session http1;
        struct http2_session http2;
    }
};

• attachment - параметр для использования в коллбэках, переданный при инициализации парсера

http1_session

Контекст парсера HTTP/1 содержит контекст единственного потока данных.

struct http1_session {
    http_stream *stream;
};

http2_session

Контекст парсера HTTP/2 содержит контекст настройки nghttp2-сессии и карту контекстов для каждого потока.

struct http2_session {
    nghttp2_session session;
    // int -> http_stream *
    hash_t() stream_id_to_stream;
};

http_stream

Контекст одного потока HTTP, содержит заголовки текущего запроса или ответа.

struct http_stream {
    void *attachment;
    // PRIVATE FIELDS
    ...
};

• attachment - параметр для использования в коллбэках, переданный при инициализации парсера

http_session_type

Тип парсера - HTTP-запрос, HTTP-ответ, HTTP/2

enum http_session_type {
    HTTP_REQUEST,
    HTTP_RESPONSE,
    HTTP2
};

Функции

logger_open

Открывает лог

logger *logger_open(const char *filename, logger_log_level_t log_level, logger_callback_t callback, void *attachment);

• filename - имя лог-файла
• log_level - уровень логгирования
• callback - коллбэк логгирования
• attachment - параметр коллбэка логгирования
• возвращаемое значение - контекст логгера

logger_log

Записывает сообщение в лог

void logger_log(logger *log, logger_log_level_t log_level, const char *fmt, ...);

• log - контекст логгера
• log_level - уровень логгирования
• fmt - строка формата
• ... - параметры строки формата

logger_close

Закрывает лог

logger_close(logger_t *ctx);

• ctx - контекст логгера

http_session_init

Инициализирует парсер

int init(logger *log, session_type type, session_callbacks *callbacks, void *attachment, session **p);

• log - контекст логгера
• type - Тип парсера
• callbacks - Коллбэки
• attachment - Параметр коллбэков
• p - поинтер на переменную поинтера на контекст
• return value - код ошибки

http_session_input

Передает на обработку полученные данные

int input(http_session *session, const char *buffer, int length);

• session - Контекст парсера
• buffer - Буфер с данными
• length - Размер буфера
• return value - код ошибки

http_session_input_settings

Передает на обработку значение заголовка HTTP2-Settings при апгрейде с HTTP/1.1

int input_settings(http_session *context, const char *base64_http2_settings, int length);

• context - Контекст парсера
• base64_http2_settings - Значение заголовка HTTP2-Settings при апгрейде с HTTP/1.1
• length - Длина заголовка
• return value - код ошибки

http_session_close

Освобождает ресурсы парсера

int close(http_session *session);

• id - ID соединения
• return value - код ошибки

Коллбэки

h1_headers

Сигнализирует о получении всех заголовков

void h1_headers(http_stream *stream, struct http_headers headers);

• stream - контекст потока (единственного)
• headers - заголовки после распаковки

h1_data_started

Сигнализирует о начале передачи данных

bool h1_data_started(http_stream *stream);

• stream - контекст потока (единственного)
• возвращаемое значение - нужно ли применять zlib-декомпрессию данных потока

h1_data

Сигнализирует о получении данных

void h1_data(http_stream *stream, const char *data, size_t length);

• stream - контекст потока (единственного)
• stream_id - идентификатор потока
• data - массив байт с данными
• length - длина массива байт с данными

h1_data_finished

Сигнализирует о завершении получения данных

void h1_data_finished(http_stream *stream, rst_stream_flag rst_stream);

• stream - контекст потока (единственного)
• rst_stream - сигнал о том, что поток сброшен с помощью фрейма RST_STREAM, а не окончен с флагом END_STREAM

h2_frame

Сигнализирует о получении HTTP/2 фрейма

void h2_frame(http_stream *stream, unsigned int stream_id, enum h2_frame_type type,
              struct frame_any frame);

• stream - контекст потока
• stream_id - идентификатор потока
• type - тип фрейма
• frame - структура фрейма

h2_headers

Сигнализирует о получении всех заголовков в данном потоке

void h2_headers(http_stream *stream, unsigned int stream_id, struct http_headers headers);

• stream - контекст потока
• stream_id - идентификатор потока
• headers - заголовки после распаковки

h2_data_started

Сигнализирует о начале передачи данных в данном потоке

bool h2_data_started(http_stream *stream, unsigned int stream_id);

• stream - контекст потока
• stream_id - идентификатор потока
• возвращаемое значение - нужно ли применять zlib-декомпрессию данных потока

h2_data

Сигнализирует о получении фрейма с данными в данном потоке

void h2_data(http_stream *stream, unsigned int stream_id, struct frame_data data);

• stream - контекст потока
• stream_id - идентификатор потока
• data - структура фрейма с данными

h2_data_finished

Сигнализирует о завершении получения данных в данном потоке

void h2_data_finished(http_stream *stream, unsigned int stream_id, rst_stream_flag rst_stream);

• stream - контекст потока
• stream_id - идентификатор потока
• rst_stream - сигнал о том, что поток сброшен с помощью фрейма RST_STREAM, а не окончен с флагом END_STREAM

Utility methods

Создание, клонирование, модифицирование структур библиотеки.

Comments