xs.json подробно · поля уровня сервиса

Обзор

7.1 Введение

У конфигурационных систем две типовые болезни. Первая — расхлябанность: поле с опечаткой молча игнорируется и всплывает только в продакшне. Вторая — рассеяние: поведение размазано по конфигам, переменным окружения и командной строке. Ответ xs.json — fail-fast и единый источник: любое недопустимое предустановленное поле называется и отклоняется при старте, а любое непредустановленное поле без изменений уходит в Custom приложению — поле, которого хост не знает, никогда не проглатывается и никогда не получает угаданного смысла.

7.2 Пять классов протоколов (class)

Значения вне белого списка сразу fail-fast. Критерий выбора прост: что говорит браузер — http/ws; байтовые потоки — tcp; без соединений — udp; остальное делайте сами.

7.3 Поля эндпоинтов

{
    "ip": "0.0.0.0",        /* адрес прослушивания, по умолчанию все интерфейсы */
    "port": 80,             /* порт открытого текста, обязателен кроме custom */
    "tls": true,            /* включить TLS-порт; для udp запрещено */
    "port_tls": 443,        /* по умолчанию 443; конфликт с портом открытого текста на том же IP отклоняется */
    "ip_tls": "0.0.0.0"     /* по умолчанию совпадает с ip */
}

Что только что произошло: у сервиса максимум два эндпоинта (открытый текст + TLS). Правило конфликтов — проверка на старте: совпадение портов открытого текста и TLS на одном IP отклоняется сразу, никакого молчаливого «последний победил». Пути сертификатов — не уровень сервиса: они на уровне хоста (глава 8); уровень сервиса решает только «нужен ли TLS-порт».

7.4 Поля лимитов

recv_limit — линия обороны памяти: потолок данных, втягиваемых за одно чтение. На tcp он формирует пик буфера соединения; на udp дейтаграммы по природе ≤64 КБ, поэтому потолок ужат до 65535. Запросные лимиты header/body — не предустановленные поля сервиса: это ручки Custom (глава 9), их читает http-драйвер.

7.5 Скриптовые умолчания уровня сервиса

Пять скриптовых полей можно указать на уровне сервиса как умолчания для всех хостов:

{
    "class": "http",
    "name": "my-site",
    "port": 8080,
    "path": "wwwroot",       /* корень статики */
    "devlang": "c",          /* язык скрипта */
    "devfile": "main.c",     /* вход скрипта */
    "dev_inc": "includes",   /* доп. каталоги заголовков (через точку с запятой) */
    "dev_lib": "librarys"    /* доп. каталоги библиотек */
}

Если host_default не задан, эти пять полей синтезируют DefaultHost — именно поэтому минимальному приложению главы 4 host_default не понадобился. Одноимённые поля уровня хоста переопределяют по одному.

7.6 Контракт

• Валидация: белый список class, port 1–65535, взаимоисключение tls×udp, конфликты портов — всё называется и уходит в fail-fast при старте.
• Умолчания: скриптовые поля уровня сервиса — лишь источник умолчаний для уровня хоста, не вторая система конфигурации.
• Уникальность: name глобально уникален — это ключ xsServerFind в рантайме и описание цели reload.

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

{ "ip": "0.0.0.0", "port": 8080,
  "tls": true, "port_tls": 8080 }

{ "ip": "0.0.0.0", "port": 8080,
  "tls": true, "port_tls": 8443 }

{ "class": "udp", "port": 9000,
  "tls": true }

{ "class": "udp", "port": 9000 }

Упражнения