Основы HTTP: структура-представление и трёхзначный возврат

Обзор

14.1 Введение

Для HTTP-бизнеса нужны три вещи: знать, что за запрос (метод, путь, заголовки, тело), знать, куда писать ответ (транспорт) и знать, кто забирает управление после вас. Большинство фреймворков мнут всё это в объект Request/Response, меняя абстракцию на удобство; XServer выдаёт три вещи раздельно — шесть полей XS_HttpReq и есть их адреса.

14.2 XS_HttpReq по полям

typedef struct {
    xnetstream*       tcp;    /* ровно один из tcp/tls не пуст: голый транспорт */
    xtlsstream*       tls;    /*   применим весь потоковый/отправочный API xrt  */
    const xhttp1head* head;   /* вкл. MethodCode; представление валидно в колбэке */
    xhttp1body*       body;   /* автомат кадрирования: фикс / chunked / close     */
    const XS_HostInfo*  host;
    XS_ServerInfo*    server;
} XS_HttpReq;

Почему нет поля Response? — потому что ответ не объект, а поток байтов, который вы пишете в транспорт. В этом предельность «нуля обёрток»: нет скрытого буфера ответа — значит, нет и вопросов класса «когда фреймворк делает flush».

14.3 Чтение заголовков запроса

static XS_RequestResult RequestProc(XS_HttpReq* pReq)
{
    /* метод: битовая маска — одновременно и метод, и элемент множества (ref-enums) */
    if ( pReq->head->MethodCode == XHTTP_METHOD_GET ) { ... }

    /* представления пути и полей: xstrview = указатель + длина, валидны в колбэке */
    /* конкретные API доступа (поиск полей / разбор пути) — в xrt · http1 */
    return XS_FALLBACK;
}

Два железных правила чтения головы: первое — представления полей head действительны только в стеке данного колбэка — XServer копирует заголовок запроса на фазе PinHead, чтобы помешать переиспользованию ring-буфера, но после смены поколения/конца запроса они всё равно истекают; второе — не сравнивайте пути C-строковыми функциями: у представлений есть длина, сравнивайте по длине (инструменты xrtStrView).

14.4 Момент вызова и потоки

• По разу на запрос; на keep-alive-соединении вызывается на каждый запрос
• Конкурентность workers — RequestProc обязан быть реентерабельным (без изменяемых межзапросных статиков или с собственной блокировкой)
• Между драйвером и скриптом действует перекрёстная сверка потреблённых байтов: расхождение заявленного с фактическим в сети рвёт соединение — скрипт рассматривается как недоверенная граница

14.5 Контракт

• Заимствование: все шесть полей действительны внутри колбэка; значения можно копировать, указатели нельзя.
• Трёхзначность: перед XS_OK ответ дописан; один записанный байт запрещает FALLBACK; после TAKEOVER драйвер отходит.
• Конкурентность: RequestProc исполняется конкурентно на workers — реентерабельность есть жёсткое требование.

Частые ошибки

if ( strcmp(pPath, "/api") == 0 )

/* сравнение по длине представления (инструменты xrtStrView) */

Упражнения