shad-go/distbuild/README.md

# distbuild

В этом задании вам нужно будет реализовать систему распределённой сборки.

Система сборки получает на вход граф сборки и файлы с исходным кодом. Результатом сборки
являются исполняемые файлы и stderr/stdout запущенных процессов.

## Граф сборки

Граф сборки состоит из джобов. Каждый джоб описывает команды, которые нужно запустить на одной машине,
вместе со всеми входными файлами, которые нужны этим командам для работы.

Джобы в графе сборки запускают произвольные команды. Например, вызывать компилятор, линкер или 
запускать тесты.

Команды внутри джоба могут читать файлы с файловой системы. Мы будем различать два вида файлов:
 - Файлы с исходным кодом с машины пользователя.
 - Файлы, которые породили другие джобы.

Команды внутри джоба могут писать результаты своей работы в файлы на диске. Выходные файлы
обязаны находиться внутри `OUTPUT_DIR` директории.

```go
package graph

import "crypto/sha1"

// ID задаёт уникальный идентификатор джоба.
//
// Мы будем использовать sha1 хеш, поэтому ID будет занимать 20 байт.
type ID [sha1.Size]byte

// Job описывает одну вершину графа сборки.
type Job struct {
    // ID задаёт уникальный идентификатор джоба.
    //
    // ID вычисляется как хеш от всех входных файлов, команд запуска и хешей зависимых джобов.
    //
    // Выход джоба целиком опеределяется его ID. Это важное свойство позволяет кешировать
    // результаты сборки.
    ID ID

    // Name задаёт человекочитаемое имя джоба.
    //
    // Например:
    //   build gitlab.com/slon/disbuild/pkg/b
    //   vet gitlab.com/slon/disbuild/pkg/a
    //   test gitlab.com/slon/disbuild/pkg/test
    Name string

    // Inputs задаёт список файлов из директории с исходным кодом, 
    // которые нужны для работы этого джоба.
    //
    // В типичном случае, тут будут перечислены все .go файлы одного пакета.
    Inputs []string

    // Deps задаёт список джобов, выходы которых нужны для работы этого джоба.
    Deps []ID

    // Cmds описывает список команд, которые нужно выполнить в рамках этого джоба.
    Cmds []Cmd
}

// Cmd описывает одну команду сборки.
//
// Есть несколько видов команд. Все виды команд описываются одной структурой.
// Реальный тип определяется тем, какие поля структуры заполнены.
//
//   exec - выполняет произвольную команду
//   cat  - записывает строку в файл
//
// Все строки в описании команды могут содержать в себе на переменные. Перед выполнением
// реальной команды, переменные заменяются на их реальные значения.
//
//   {{OUTPUT_DIR}} - абсолютный путь до выходной директории джоба.
//   {{SOURCE_DIR}} - абсолютный путь до директории с исходными файлами.
//   {{DEP:f374b81d81f641c8c3d5d5468081ef83b2c7dae9}} - абсолютный путь до директории,
//   содержащей выход джоба с id f374b81d81f641c8c3d5d5468081ef83b2c7dae9.
type Cmd struct {
    // Exec описывает команду, которую нужно выполнить.
    Exec []string

    // Environ описывает переменные окружения, которые необходимы для работы команды из Exec.
    Environ []string
    
    // WorkingDirectory задаёт рабочую директорию для команды из Exec.
    WorkingDirectory string

    // CatTemplate задаёт шаблон строки, которую нужно записать в файл.
    CatTemplate string

    // CatOutput задаёт выходной файл для команды типа cat.
    CatOutput string
}
```

## Архитектура системы

Наша система будет состоять из трех компонент.
 * Клиент - процесс запускающий сборку.
 * Воркер - процесс запускающий команды компиляции и тестирования.
 * Координатор - центральный процесс в системе, общается с клиентами и воркерами. Раздаёт задачи
   воркерам.

Типичная сборка выглядит так:
1. Клиент подключается к координатору, посылает ему граф сборки и входные файлы для графа сборки.
2. Кооринатор сохраняет граф сборки в памяти и начинает его исполнение.
3. Воркеры начинают выполнять вершины графа, пересылая друг другу выходные директории джобов.
4. Результаты работы джобов скачиваются на клиента.

## Протоколы

Общение между компонентами будет происходить поверх HTTP и json. В реальной системе мы бы
взяли более продвинутый протокол и более эффективный формат сериализации, но в этой учебной
задаче нам важнее уменьшить сложность системы.

### Протокол: Клиент <-> Координатор

При общении клиента и кординатора, клиент всегда выступает инициатором запроса.

* `POST /build` - стартует новый билд. Клиент посылает в Body запроса json c описанием сборки. Сервер
стримит в body ответа json сообщения описывающие прогресс сборки (тут правильнее было бы использовать
websocket, но нас устраивает более простое решение).

* `POST /source/{sha1}` - загружает файл с исходным кодом на координатор. Клиент посылает
содержимое файла в body запроса. `{sha1}` - равен `{sha1}` хешу от содержимого файла.

### Протокол: Координатор <-> Воркер

При общении воркера и координатора, воркер всегда выступает инициатором запроса.

* `GET /source/{sha1}` - скачивает файл с исходным кодом с координатора.

* `POST /heartbeat` - синхронизирует состояние воркера и координатора. Воркер посылает
в теле запроса json описывающий изменение в своём состоянии. Коордитора отвечает json-ом со
списком задач, которые должен выполнить воркер.

```go
package proto

// CompleteJob описывает результат работы джоба.
type CompletedJob struct {
    ID graph.ID

    Stdout, Stderr []byte

    // Error описывает сообщение об ошибке, из-за которого джоб не удалось выполнить.
    //
    // Если Error == nil, значит джоб завершился успешно.
    Error *string
}

type HeartbeatRequest struct {
    // WorkerID задаёт персистентный идентификатор данного воркера.
    //
    // WorkerID так же выступает в качестве endpoint-а, к которому можно подключиться по HTTP.
    //
    // В наших тестов, идентификатор будет иметь вид "localhost:%d".
    WorkerID string

    // ProcessID задаёт эфемерный идентификатор текущего процесса воркера.
    //
    // Координатор запоминает ProcessID для каждого воркера.
    //
    // Измение ProcessID значит, что воркер перезапустился.
    ProcessID string

    // RunningJobs перечисляет список джобов, которые выполняются на этом воркере
    // в данный момент.
    RunningJobs []graph.ID

    DownloadingSources []graph.ID

    DownloadingArtifacts []graph.ID

    // FreeSlots сообщаяет, сколько еще процессов можно запустить на этом воркере.
    FreeSlots int

    // CompletedJobs сообщает координатору, какие джобы завершили исполнение на этом воркере
    // на этой итерации цикла.
    CompletedJobs []CompletedJob

    // AddedArtifacts говорит, какие артефакты появились в кеше на этой итерации цикла.
    AddedArtifacts []graph.ID

    // AddedSourceFiles говорит, какие файлы появились в кеше на этой итерации цикла.
    AddedSourceFiles []graph.ID
}

// JobSpec описывает джоб, который нужно запустить.
type JobSpec struct {

}

// ArtifactSpec описывает артефакт, который нужно скачать с другого воркера.
type ArtifactSpec struct {

}

// SourceFileSpec описывает файл с исходным кодом, который нужно скачать с координатора.
type SourceFileSpec struct {

}

type HeartbeatResponse struct {
    JobsToRun map[graph.ID]JobSpec

    ArtifactsToDownload map[graph.ID]ArtifactSpec

    ArtifactsToRemove []graph.ID

    SourceFilesToDownload map[graph.ID]SourceFileSpec

    SourceFilesToRemove []graph.ID
}
```

### Протокол: Воркер <-> Воркер

Общение между воркерам происходит тогда, когда системе нужно передать артефакты сборки с
одного воркера на другой.

* `GET /artifact/{sha1}` - возвращает директорию с выходными данными джоба в формате `tar`.

## Кеширование

### Кеш исходного кода

### Кеш артефактов

## Тестирование