Анатомия минимального приложения: два файла — один сервис

Обзор

4.1 Введение

«Hello world» большинства фреймворков проходит сквозь пять слоёв абстракции: регистрация входа → сопоставление маршрутов → цепочка middleware → объект контекста → сериализация ответа. Философия XServer противоположна: сначала выдать минимальные факты протокола — разобранный заголовок запроса, указатели транспорта, автомат кадрирования — и отойти в сторону. Поэтому минимальное приложение действительно минимально:

Ниже — построчный разбор этих двух фактов. Они взяты из реальных файлов demo-single, из них лишь вырезана бизнес-часть.

4.2 xs.json построчно

{
    "services": [
        {
            "enabled": true,          /* выключатель сервиса */
            "class": "http",          /* класс протокола: http/ws/tcp/udp/custom */
            "name": "demo",           /* глобально уникальное имя, ключ xsServerFind */
            "ip": "127.0.0.1",
            "port": 9080,
            "host_default": {         /* хост по умолчанию: откат, когда vhost не совпал */
                "enabled": true,
                "name": "app",
                "path": "wwwroot",    /* корень статики */
                "devlang": "c",       /* c = скрипт TCC; static = чистая статика */
                "devfile": "main.c"   /* вход скрипта (относительно каталога конфига) */
            }
        }
    ]
}

Что только что произошло: конфигурация объявляет цепочку фактов — слушать HTTP на 127.0.0.1:9080; запросы, не попавшие в другие vhost, уходят хосту по умолчанию app; корень статики app — wwwroot; бизнес-логика в main.c. Любое неверное поле (опечатка в class, порт вне диапазона) ломает старт до строки config loaded и называет конкретное поле — полная таблица полей в руководстве · конфигурация, том 2 разбирает каждое.

4.3 main.c построчно

#include <xsbase.h>   /* контрактный заголовок: подтягивает xrt_decl.h и libtcc.h (всё в VFS) */

/* вызывается один раз после загрузки поколения (управляющий поток сборки / reload) */
static void ServiceInit(XS_HostInfo* pHost)
{
    printf("[%s] service init\n", pHost->Name);
}

/* по разу на запрос (worker-потоки движка, возможна конкурентность) */
static XS_RequestResult RequestProc(XS_HttpReq* pReq)
{
    /* необработанные запросы → откат в статический слой (wwwroot), остальное 404 */
    return XS_FALLBACK;
}

/* вызывается при утилизации поколения (GC-поток, не более одного раза за жизнь) */
static void ServiceUnit(XS_HostInfo* pHost)
{
    printf("[%s] service unit\n", pHost->Name);
}

Что только что произошло:

• #include <xsbase.h> не требует установки — заголовок вместе с полными объявлениями xrt лежит в VFS внутри exe, TCC читает его напрямую;
• хост ищет ServiceInit / RequestProc / ServiceUnit по имени символа (static не прячет — в памяти-режиме TCC символы видны), все они необязательны;
• три функции ровно соответствуют трём моментам поколения из главы 3: рождение / обслуживание / утилизация.

Запустим (вывод с реальной машины):

$ ./xs
[xs] config loaded: .../xs.json (1 servers)
[xs] script loaded: .../main.c (0.4 KB gen 1)
[app] service init
[xs] server 'demo' http bound on 127.0.0.1:9080
[xs] running, press Ctrl+C to stop

$ curl -s http://127.0.0.1:9080/
<!DOCTYPE html> ...          /* wwwroot/index.html — / забрал статический слой */

4.4 Трёхзначный возврат

Возврат RequestProc — это не «успех / провал», а кто отвечает за остаток жизни запроса:

4.5 Откат в статический слой

После XS_FALLBACK в дело вступает статический слой хоста: он ищет файлы в path хоста (здесь wwwroot) — GET отдаёт содержимое, HEAD только заголовки, с percent-decode, индексами каталогов (по умолчанию index.html) и отказом для файлов с точкой. Так / выше и получил index.html. Четыре ручки статического слоя (свои заголовки, страницы ошибок, индексы, deny_dotfiles) открываются в главе 10 тома 2.

Связка «сначала скрипт, статика как подстраховка» избавляет от кода для статики — и от правил рерайта для динамических маршрутов.

4.6 Контракт

• Символы: контрактные символы ищутся по имени, все необязательны — хост без экспортированного RequestProc просто чисто статический сайт.
• Владение: XS_HttpReq и указатели внутри действительны только в стеке колбэка; в нашем примере голый return безрисков, но как только начнёте пользоваться представлениями — работают правила главы 3.
• Ответственность: вернуть XS_OK — значит «полный ответ написан»: заголовок + тело (кроме HEAD) в зоне вашей ответственности.

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

static XS_RequestResult
RequestProc(XS_HttpReq* pReq)
{
    if ( path is mine ) ...;
    /* нет return: мусор случайно попадает в состояние */
}

static XS_RequestResult
RequestProc(XS_HttpReq* pReq)
{
    if ( path is mine ) return XS_OK;
    return XS_FALLBACK;   /* явная концовка */
}

xrtNetStreamSend(pReq->tcp,
    "HTTP/1.1 200 OK\n\nhello", 22);
return XS_OK;   /* сообщение неполное, без длины */

/* заголовок строит xrtHttp1ResponseWrite
 * (глава 15 сделает полную обёртку) */

ConnSend(pReq, head, n);
if ( !hasBody ) return XS_FALLBACK;

/* решение принимается до записи:
 * либо полный ответ + XS_OK,
 * либо ничего не пишем + FALLBACK */

Упражнения