Головна/Завдання/Частина 4/Службовий контракт

Службовий контракт бота

Бот у здачі - не скрипт, а сервіс. Чотири ручки нормовано: /health, /metrics, /belief-stream і /presets/promote. За двома першими конвеєр судить про готовність стека, решта дві потрібні вашому штабу.

опубліковано 21.09

Шлях - корінь, порт - ваш (мітка zaria.control, за замовчуванням 7801). Слухати треба всі інтерфейси (0.0.0.0): перевірка приходить зовні контейнера, і ручка на 127.0.0.1 для неї "не встала". Автентифікації в ручок немає і не потрібно: мережа стека назовні не виходить, а назовні стирчить тільки те, що ми спитаємо самі.

1`GET /health` - обов'язкова

Готовність і життя однією відповіддю. На ній стоять ступені up і health передстартового прогону (03-preflight.md).

схема

$ curl -s localhost:7801/health
{"status":"ok","state":"live","slot":"A","preset":"рівний","tick":412,
 "frames":410,"ticks":1200,"why":"","engine":"264a77c2a5405955f5aba04be240325d65cfe5d25269ae2f7c6a9fc7f4ff0e26","uptimeMs":209417}

1.1

Неготовий бот відповідає 503, а не 200 із сумним полем. Готовність означає "провід живий або прогін чесно закінчено". Лобі, простій, перескладання, відмова присяги і аварійний кінець - 503.

1.2

Поле status: ok - готовий, starting - лобі або простій, failed - прогін закінчився не прощанням; причина - у why.

1.3

tick - такт світу з останнього кадру спостереження, frames - кадрів, на які бот відповів. Різниця - пропущені такти. engine - повний хеш рушія, той самий, що в hello.ack.

1.4

Прогін дивиться /health двічі: до партії проби (чекає готовності) і після неї (чекає 200). Бот, який після чесного кінця партії відповідає 503, ступінь не проходить.

2`GET /metrics` - обов'язкова

Формат Prometheus. П'ять лічильників обов'язкові; ступінь metrics перевіряє саме їхню наявність.

Лічильник	Тип	Що означає
`bot_ticks_processed`	counter	тактів оброблено на проводі
`bot_orders_sent`	counter	кадрів команд надіслано
`bot_nacks`	counter	відмов воротаря
`bot_resync_seconds`	counter	секунд на присягу і перескладання картини світу, включно з кожним поверненням після обриву
`bot_belief_snapshot_age`	gauge	секунд від останнього кадру віри

Свої лічильники додавайте скільки завгодно; канонні прибирати не можна - за цими п'ятьма ми читаємо всіх ботів однаково. Рахунок коду 25 їх не використовує: він рахується за телеметрією вузла і за журналами (scoring.md, 8).

3`GET /belief-stream` - для штабу

Потік власного щоденника віри: кадр на такт, той самий, що йде в NDJSON на диск. Це живі очі вашого штабу на вашій машині.

схема

$ curl -sN localhost:7801/belief-stream | head -2
data: {"t":413,"full":false,"pulse":{...},"own":{...}}

Назовні із залікової партії потік не ходить: машини учасників в ізоляції за вихідним трафіком. Спостереження за поточною партією (Ш5) ваш штаб отримує від господаря показу (part3/01-hq-contract.md, розділ 2), а /belief-stream працює у вас локально і на тренувальному дні.

4`GET /presets` і `POST /presets/promote` - для штабу

Зміна активної стратегії без перезбирання образу. Нормується лише POST /presets/promote; GET /presets - допоміжна ручка понад контракт, шаблон її віддає.

схема

$ curl -s localhost:7801/presets
{"active":"рівний","known":["рівний","шир","обхідник","проривник","облягач"]}

$ curl -s -X POST localhost:7801/presets/promote -H 'content-type: application/json' \
       -d '{"preset":"обхідник"}'
{"preset":"обхідник"}     # 200 прийнято
                          # 409 іде прогін або здачу заморожено
                          # 400 пресета з таким іменем немає

4.1

Посеред прогону промоут відхиляється завжди: зміна стратегії в бою була б зміною гравця. На заліковій партії вузол кладе голові ZARIA_FREEZE=1, і промоут мусить відповідати 409, навіть між партіями пакета: образи і грамота заморожені з фіксації коміту (01-submit.md, 1.2, 1.4).

4.2

Звідси і задача Ш4-4 вашого штабу: показати відповідь, яка прийшла, а не ту, яку хотілося. Пресети влаштовуєте ви; список імен у /presets теж ваш.

5Чого в контракті немає

5.1

Ручки керування партією: садити бота за стіл, зупиняти його, правити команди. Адреса вузла і печатка приходять змінними ZARIA_URL і ZARIA_TOKEN (02-build.md, розділ 7); ручка на кшталт POST /run - ваша місцева зручність, у контракт вона не входить.

5.2

Важелів (restart, profile, failover) у сезоні немає: під час партії у вашу машину ніхто не ходить.

5.3

Щоденник рішень ("чому бот так сходив") не нормовано: щоденник віри несе стан, а не мотив. Свій щоденник рішень корисний вам самим і вашому розбору DECISIONS.md (scoring.md, 10.1); склеюється він із журналом партії за номером такту.