From 1a43240b128387501d74f3780ea38a65127f5ad0 Mon Sep 17 00:00:00 2001 From: Nikolay Gagarinov Date: Thu, 3 Sep 2026 21:48:13 +0500 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=B5=D1=80=D0=B2=D0=B5=D1=80=20?= =?UTF-8?q?=D1=8D=D1=82=D0=BE=20=D0=BA=D0=BE=D0=BD=D1=82=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=20=D0=BA=D1=83=D1=80=D1=81=D0=B0,=20=D0=B0=20=D0=BD=D0=B5=20?= =?UTF-8?q?=D0=B4=D0=B5=D1=82=D0=B0=D0=BB=D1=8C=20=D1=80=D0=B5=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README сообщал только команды, и по нему нельзя было понять, что на сервер живьём ходят студенты и что уроки цитируют его ответы дословно. Теперь он называет проект и отсылает к AGENTS.md до первой правки. В AGENTS.md пять фактов, каждый из которых снаружи выглядит не тем, чем является: значения полей только на латинице (сервер один на все локали курсов); дефолты skip и limit несут пагинацию, и без них limit молча перестаёт работать; make generate очищает generated/ перед записью; сервисы в тесте снимаются группой по PID, потому что pkill -f совпадает с текстом своей же команды; трейлинг-слеш даёт 404. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 10 ++++++++++ README.md | 16 ++++++++++++---- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 40eecaa..9f9e2e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,6 +110,8 @@ Caddy :$PORT * **Валидация отвечает 400, уроки учат на 422.** Отображение делает `setErrorHandler` в `http-api.ts` по коду `FST_ERR_VALIDATION`. +**Дефолты `skip` и `limit` в спецификации несут пагинацию.** `skip: uint16 = 0` и `limit: uint16 = 30` выглядят необязательными, но значение по умолчанию подставляет валидатор, и без них пагинация ломается **частично**: `skip` продолжает работать, `limit` перестаёт. Снаружи это читается как «limit не поддерживается», хотя причина в правке спецификации. + ## Примеры ответов это текст уроков Значения в `@example` подобраны под то, что уроки уже печатают: @@ -155,6 +157,8 @@ Caddy :$PORT Проверку всех кодов держит `make test`. +**Трейлинг-слеш маршруты не прощают:** `/postman/users/` отдаёт 404. В текстах курсов адрес пишется без слеша. + ## Версии прибиты не для порядка Зависимости на prism больше нет. Если мок когда-нибудь вернут, с ним вернутся и @@ -181,6 +185,10 @@ Caddy :$PORT типы из него и падает на `git diff`, хотя спецификации в репозитории не менялись. Лечится `make compile`. +**`make generate` очищает `custom-server/src/generated/` перед записью.** Неудачная проба сносит закоммиченное, поэтому сгенерированное восстанавливается из git, а не переписывается руками. + +Сервисы в тесте заводятся `detached: true` и снимаются группой (`process.kill(-pid)`): без этого внук `npx` переживает `SIGTERM` обёртке и держит трубы открытыми. Трубу обязательно вычитывать. Процессы снимаются по PID, потому что `pkill -f "fastify start"` совпадает с текстом собственной команды и убивает свою же оболочку. Пустой вывод **у всех** сервисов сразу означает нехватку ресурсов машины, а не поломку кода. + Caddy в прогоне не участвует, в раннере его нет: порты опрашиваются напрямую, как это делает Caddy со срезанным префиксом. Сборка гоняется и на пуллреквестах, публикация образа — только с `main`. @@ -220,6 +228,8 @@ make deploy APP=http_example HOST=timeweb SKIP=caddy,cron * первые три пользователя и первые два поста автора 1 приведены в уроке дословно. +**Значения полей только на латинице.** Сервер один на все локали курсов, и русский текст в ответе читался бы как ошибка у испанского студента. По-русски здесь пишутся комментарии в коде и спецификациях, не данные. + ## Набор данных не меняется `POST` и `DELETE` отвечают 201 и 204, но список задач остаётся прежним: создание diff --git a/README.md b/README.md index 12e260d..e3aa7e2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,10 @@ - +# http-example + +Учебный HTTP-сервер Хекслета: [https://http.hexlet.app](https://http.hexlet.app). На него **живьём ходят студенты** из курсов HTTP API, протокол HTTP, Postman и js-playwright, а уроки и самостоятельные работы цитируют его ответы дословно, вплоть до значений полей. + +Отсюда главное свойство проекта: **ответы сервера это контент курса**, а не деталь реализации. Правка данных здесь делает неверным текст урока в другом репозитории, и по коду это не видно. Поэтому правила работы с проектом собраны в [AGENTS.md](./AGENTS.md), и читать их стоит до первой правки — там же разобрано, почему наборы данных такого размера, почему они не меняются и какие коды ответов несут уроки. + +Устройство короткое: четыре спецификации на TypeSpec (`typespec//`, по одной на курс) компилируются в OpenAPI, а маршруты, валидацию и авторизацию строит из них `fastify-openapi-glue`. Руками написаны только данные и то, что в OpenAPI не выражается. Значит документация и поведение разъехаться не могут: студент читает ту же спецификацию, по которой работает сервер. ## Prerequisites @@ -7,13 +13,15 @@ ## Commands -See [Makefile](./Makefile) - ```bash +make setup # зависимости и компиляция спецификаций +make test # прогон против всех четырёх префиксов make compose-build -make compose # Open http://localhost:8080 +make compose # http://localhost:8080 ``` +Остальные цели — в [Makefile](./Makefile). + --- [![Hexlet Ltd. logo](https://raw.githubusercontent.com/Hexlet/assets/master/images/hexlet_logo128.png)](https://hexlet.io?utm_source=github&utm_medium=link&utm_campaign=http-example)