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

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(запрос: HttpRequest) -> HttpResponse {
  if запрос.method == "GET" && запрос.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 выполняйте на обратном прокси.

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