api

README

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 и используйте его.
  • Первым сообщением в ответе 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 возвращается пользователю.

Documentation

Index

• type BuildClient
  • func NewBuildClient(l *zap.Logger, endpoint string) *BuildClient
  • func (c *BuildClient) SignalBuild(ctx context.Context, buildID build.ID, signal *SignalRequest) (*SignalResponse, error)
  • func (c *BuildClient) StartBuild(ctx context.Context, request *BuildRequest) (*BuildStarted, StatusReader, error)
• type BuildFailed
• type BuildFinished
• type BuildHandler
  • func NewBuildService(l *zap.Logger, s Service) *BuildHandler
  • func (h *BuildHandler) Register(mux *http.ServeMux)
• type BuildRequest
• type BuildStarted
• type HeartbeatClient
  • func NewHeartbeatClient(l *zap.Logger, endpoint string) *HeartbeatClient
  • func (c *HeartbeatClient) Heartbeat(ctx context.Context, req *HeartbeatRequest) (*HeartbeatResponse, error)
• type HeartbeatHandler
  • func NewHeartbeatHandler(l *zap.Logger, s HeartbeatService) *HeartbeatHandler
  • func (h *HeartbeatHandler) Register(mux *http.ServeMux)
• type HeartbeatRequest
• type HeartbeatResponse
• type HeartbeatService
• type JobResult
• type JobSpec
• type Service
• type SignalRequest
• type SignalResponse
• type StatusReader
• type StatusUpdate
• type StatusWriter
• type UploadDone
• type WorkerID
  • func (w WorkerID) String() string

Types

type BuildClient

type BuildClient struct {
}

func NewBuildClient

func NewBuildClient(l *zap.Logger, endpoint string) *BuildClient

func (*BuildClient) SignalBuild

func (c *BuildClient) SignalBuild(ctx context.Context, buildID build.ID, signal *SignalRequest) (*SignalResponse, error)

func (*BuildClient) StartBuild

func (c *BuildClient) StartBuild(ctx context.Context, request *BuildRequest) (*BuildStarted, StatusReader, error)

type BuildFailed

type BuildFailed struct {
	Error string
}

type BuildFinished

type BuildFinished struct {
}

type BuildHandler

type BuildHandler struct {
}

func NewBuildService

func NewBuildService(l *zap.Logger, s Service) *BuildHandler

func (*BuildHandler) Register

func (h *BuildHandler) Register(mux *http.ServeMux)

type BuildRequest

type BuildRequest struct {
	Graph build.Graph
}

type BuildStarted

type BuildStarted struct {
	ID           build.ID
	MissingFiles []build.ID
}

type HeartbeatClient

type HeartbeatClient struct {
}

func NewHeartbeatClient

func NewHeartbeatClient(l *zap.Logger, endpoint string) *HeartbeatClient

func (*HeartbeatClient) Heartbeat

func (c *HeartbeatClient) Heartbeat(ctx context.Context, req *HeartbeatRequest) (*HeartbeatResponse, error)

type HeartbeatHandler

type HeartbeatHandler struct {
}

func NewHeartbeatHandler

func NewHeartbeatHandler(l *zap.Logger, s HeartbeatService) *HeartbeatHandler

func (*HeartbeatHandler) Register

func (h *HeartbeatHandler) Register(mux *http.ServeMux)

type HeartbeatRequest

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

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

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

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

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

type HeartbeatResponse

type HeartbeatResponse struct {
	JobsToRun map[build.ID]JobSpec
}

type HeartbeatService

type HeartbeatService interface {
	Heartbeat(ctx context.Context, req *HeartbeatRequest) (*HeartbeatResponse, error)
}

type JobResult

type JobResult struct {
	ID build.ID

	Stdout, Stderr []byte

	ExitCode int

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

JobResult описывает результат работы джоба.

type JobSpec

type JobSpec struct {
	// SourceFiles задаёт список файлов, который должны присутствовать в директории с исходным кодом при запуске этого джоба.
	SourceFiles map[build.ID]string

	// Artifacts задаёт воркеров, с которых можно скачать артефакты необходимые этому джобу.
	Artifacts map[build.ID]WorkerID

	build.Job
}

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

type Service

type Service interface {
	StartBuild(ctx context.Context, request *BuildRequest, w StatusWriter) error
	SignalBuild(ctx context.Context, buildID build.ID, signal *SignalRequest) (*SignalResponse, error)
}

type SignalRequest

type SignalRequest struct {
	UploadDone *UploadDone
}

type SignalResponse

type SignalResponse struct {
}

type StatusReader

type StatusReader interface {
	Close() error
	Next() (*StatusUpdate, error)
}

type StatusUpdate

type StatusUpdate struct {
	JobFinished   *JobResult
	BuildFailed   *BuildFailed
	BuildFinished *BuildFinished
}

type StatusWriter

type StatusWriter interface {
	Started(rsp *BuildStarted) error
	Updated(update *StatusUpdate) error
}

type UploadDone

type UploadDone struct{}

type WorkerID

type WorkerID string

func (WorkerID) String

func (w WorkerID) String() string