Топаздокументация
Создание приложений

Ограниченный HTTP-сервис

Соберите, проверьте и разверните один проверенный обработчик HTTP/1.1 в ограниченном созданном процессе.

Выбирайте http-service, когда одна проверенная функция на Топазе должна получить HttpRequest и вернуть HttpResponse. Созданный платформенный процесс отвечает за приём соединений, разбор и формирование сообщений HTTP/1.1, конечные бюджеты запроса, ответы при перегрузке, журналирование и завершение работы.

Это не универсальный веб-сервер. Цель не даёт исходящих сетевых запросов, доступа к необработанным сетевым сокетам, неявного доступа к окружению, общего изменяемого состояния Топаза, TLS, HTTP/2, WebSocket или сеансов. Для публичного TLS и политики на границе Интернета поставьте перед процессом обычный обратный прокси. Эта явная граница Capability является частью устройства продукта.

Сначала завершите раздел Первое приложение. Для сборки сервиса нужен набор инструментов Rust для целевой платформы.

Создание, блокировка и тестирование

Каркас предоставляет манифест пакета, ограниченные настройки сервиса и конкретный обработчик:

BASH
topaz init --target http-service --root hello-service
topaz lock --root hello-service
topaz fmt --check --root hello-service
topaz check --root hello-service --locked
topaz test --root hello-service --locked

Входной модуль экспортирует ровно один обработчик следующей формы:

TOPAZ
import std.http { HttpRequest, HttpResponse, text }

export function handle(req: HttpRequest) -> HttpResponse {
  if req.method == "GET" && req.url.path() == "/health" {
    return text(200, "ok")
  }
  text(404, "not found")
}

Проверка отклоняет отсутствующий, обобщённый, вариативный, использующий значения по умолчанию или иначе типизированный обработчик до начала приёма соединений.

Разработка через адрес обратной петли

Запустите настоящий созданный сервис на адресе обратной петли и запросите маршрут проверки состояния:

BASH
topaz dev --root hello-service --port 8080
curl --fail-with-body http://127.0.0.1:8080/health

topaz dev принудительно использует адрес 127.0.0.1, пересобирает управляемый сервис и передаёт ему сигнал прерывания. Если порт 8080 занят, выберите другой порт на адресе обратной петли через --port.

Конечные бюджеты сервиса

Каркас записывает ограниченные значения по умолчанию в [service]:

TOML
[service]
bind = "127.0.0.1"
port = 8080
workers = 1
max_connections = 64
queue_capacity = 32
max_target_bytes = 8192
max_header_bytes = 16384
max_headers = 64
max_body_bytes = 1048576
header_timeout_ms = 5000
body_timeout_ms = 5000
handler_timeout_ms = 1000
shutdown_grace_ms = 5000
log_format = "text"

Неизвестные ключи и значения вне допустимого диапазона завершаются ошибкой при загрузке пакета. Каждый запрос получает новый контекст среды выполнения и граф модулей; запросы не разделяют общую область памяти Топаза. Переполнение очереди, слишком большой ввод, истечение времени обработчика и неверный ответ становятся ограниченными исходами процесса, а не неограниченной работой.

Сборка и проверка продукта

BASH
topaz build --root hello-service --locked --release --out-dir hello-service-product
cd hello-service-product
./target/release/program --print-config
./target/release/program

В Windows запускайте target\release\program.exe. Дерево продукта:

Вывод
hello-service-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── THIRD-PARTY-NOTICES.txt
├── target
│   └── release
│       └── program[.exe]
├── topaz-artifact.json
└── topaz-service-config.json

program[.exe] означает program в Unix и program.exe в Windows. --print-config проверяет и печатает эффективные настройки, не начиная приём соединений. Управляемый JSON-файл хранит встроенные значения. Изменения при запуске передаются явными аргументами командной строки; адрес вне интерфейса обратной петли задаётся так:

BASH
./target/release/program --bind 0.0.0.0 --port 8080

Используйте его только за запланированной сетевой границей. В манифесте разрешён лишь адрес обратной петли.

Наблюдаемые ошибки

  • Слишком большие тело, целевая часть запроса или набор заголовков дают ограниченные ошибки HTTP там, где структура запроса позволяет сформировать ответ.
  • Полная очередь обработчиков возвращает 503, а превышение времени обработчика — 504.
  • Ошибка среды выполнения или неверный ответ приложения превращается в общий 500 без путей исходников, содержимого запроса и текста ошибки Топаза.
  • Ответы и журналы процесса используют один идентификатор запроса. В журнал не попадают целевая часть запроса, тело и значения заголовков.
  • SIGINT, а в Unix и SIGTERM, прекращает приём и даёт существующей работе до shutdown_grace_ms на завершение.

Если check или test завершились ошибкой, исправьте диагностику Топаза и повторите ту же команду. Если сборка обнаружила изменённый управляемый файл или другую цель в каталоге вывода, сохраните каталог для анализа и выберите новый пустой --out-dir.

Развёртывание без исходников

Копируйте весь каталог hello-service-product/, чтобы исполняемый файл, настройки, манифест целостности, лицензии и уведомления оставались вместе. Для запуска копии не нужны исходники пакета, CLI Топаза, реестр и временное рабочее пространство Cargo. Запускайте процесс под супервизором, сохраняйте созданные бюджеты, а публичный TLS завершайте на обратном прокси.

Связанная документация