50 lines
3.5 KiB
Markdown
50 lines
3.5 KiB
Markdown
# api
|
||
|
||
Пакет api реализует протокол, по которому общаются компоненты системы.
|
||
|
||
Этот пакет не занимается передачей файлов и артефактов, соответствующие функции находятся в
|
||
пакетах `filecache` и `artifact`.
|
||
|
||
## Worker <-> Coordinator
|
||
|
||
- Worker и Coordinator общаются через один запрос `POST /heartbeat`.
|
||
- Worker посылает `HeartbeatRequest` и получает в ответ `HeartbeatResponse`.
|
||
- Запрос и ответ передаются в формате json.
|
||
- Ошибка обработки heartbeat передаётся как текстовая строка.
|
||
|
||
## Client <-> Coordinator
|
||
|
||
Client и Coordinator общаются через два вызова.
|
||
|
||
- `POST /build` - стартует новый билд.
|
||
* Client посылает в Body запроса json c описанием сборки.
|
||
* Coordinator стримит в body ответа json сообщения, описывающие прогресс сборки.
|
||
* _Тут можно было бы использовать websocket, но нас устраивает более простое решение._
|
||
* Чтобы послать клиенту неполный body, нужно использовать метод `Flush`.
|
||
Прочитайте про [`http.ResponseController`](https://pkg.go.dev/net/http#ResponseController) и используйте его.
|
||
* Первым сообщением в ответе Coordinator присылает `buildID`.
|
||
|
||
- `POST /signal?build_id=12345` - посылает сигнал бегущему билду.
|
||
* Запрос и ответ передаются в формате json.
|
||
|
||
# Замечания
|
||
|
||
- Конструкторы клиентов и хендлеров принимают первым параметром `*zap.Logger`. Запишите в лог события
|
||
получения/отправки запроса и все ошибки. Это поможет вам отлаживать интеграционные тесты
|
||
в следующей части задания.
|
||
|
||
- Все методы должны "пробрасывать" контекст.
|
||
* Контекст на клиенте нужно передать в функцию `http.NewRequestWithContext`.
|
||
* Контекст на сервере нужно получить из `r.Context()` и передать в `Service`.
|
||
|
||
- Код в этом пакете не должен запускать новые горутины.
|
||
|
||
- Ошибку из `Service.StartBuild` нужно посылать клиенту. Если эта ошибка произошла после того,
|
||
как хендлер начал писать body, то ошибку нужно передавать в потоке json-ов в поле `StatusUpdate.BuildFailed`.
|
||
|
||
- Код всех вызовов в этом пакете работает одинаково:
|
||
1. Пользователь вызывает метод `*Client`.
|
||
2. Метод делает HTTP запрос к серверу.
|
||
3. `*Handler` принимает запрос, декодирует его и передает в `*Service`.
|
||
4. (*) В случае вызова `/build`, сервис пишет обновления в `StatusWriter`, а клиентский код читает эти обновления из `StatusReader`.
|
||
5. Ответ или ошибка из `*Service` возвращается пользователю.
|