msrc
/
Readme.MD
171 строка · 10.1 Кб
1Унаследовано от "gitlab.systems-fd.com/packages/golang/servers/msrc/v3
2
3# Библиотека мультисервисного приложения для `Golang`
4
5Библиотека предназначена для реализации мультисервисных приложений на `Golang`.
6Например: У вас есть сервис, который предоставляет RestAPI, а также требуется реализация
7Websocket. По сути каждый сервис требует блокировки основной `Go-routine`, можно использовать
8дочерние `go-routine`, что по сути и делает эта библиотека.
9Также библиотека реализует `Graceful shutdown`, который позволит правильно останавливать сервисы.
10Сервис поддерживает логирование на основе `github.com/sirupsen/logrus`
11
12## Установка
13
14Необходимо включить библиотеку в один из скриптов следующим образом:
15```go
16import "gitlab.systems-fd.com/packages/golang/servers/msrc/v3"
17```
18
19Далее необходимо установить зависимости при помощи стандартной утилиты `go get`:
20```bash
21go get -u gitlab.systems-fd.com/packages/golang/servers/msrc/v3
22```
23
24## Использование
25
26Для использования библиотеки необходимо реализовать интерфейс сервиса:
27```go
28// ServiceInterface описывает интерфейс сервиса, для параллельного запуска.
29type ServiceInterface interface {
30// Run выполняет запуск сервера
31Run() error
32
33// GracefulShutdown выполняет правильную остановку сервиса
34GracefulShutdown()
35
36// IsStarted возвращает статус состояния запуска сервиса
37IsStarted() bool
38
39// IsAlive возвращает статус сервиса: живой или нет
40IsAlive() bool
41}
42```
43
44Далее необходимо использовать фабрику для генерации объекта службы:
45```go
46service := msrc.MultiService(
47map[string]multiservice.ServiceInterface{
48"Test-Service": &service{},
49},
50)
51```
52
53При передаче списка, ключ используется в качестве уникального названия сервиса.
54
55После создания объекта сервиса необходимо его запустить:
56```go
57err := service.Run()
58```
59
60В случае возникновения ошибки сервис остановит все подсервисы с использованием `Graceful shutdown`
61и вернет возникшую ошибку.
62
63## Укороченный интерфейс сервиса
64
65В библиотеку включена реализация функционала отслеживания статуса остановки и завершения
66на основе контекста. Данный функционал входит в реализацию `msrc.SimpleService`
67
68Данный сервис принимает на вход сервис с интерфейсом:
69```go
70// SimpleService описывает интерфейс упрощенного сервиса, для библиотеки.
71// Данный сервис может быть использован в случаях, когда нет необходимости
72// внутри следить за флагами состояния. Сервис должен реализовывать лишь
73// функционал работы и правильной остановки.
74type SimpleService interface {
75// Run выполняет запуск упрощенной версии сервиса.
76// На вход передается контекст, который передаст `<-ctx.Done()` в случае
77// его остановки. Сам сервис должен обрабатывать его, если он не реализует
78// своего собственного, отдельного алгоритма остановки.
79Run(ctx context.Context) error
80
81// GracefulShutdown выполняет правильную остановку упрощенного
82// сервиса. В данном случае, если сервис необходимо останавливать
83// вызовом отдельного функционала остановки, этот метод предоставляет
84// такую возможность.
85//
86// Метод вызывается в процессе остановки сервера и принимает на вход
87// контекст с deadline, устанавливаемым сверху. За установленное время
88// сервис либо завершает работу, либо отключается принудительно.
89GracefulShutdown(ctx context.Context) error
90}
91```
92
93Для превращения его в полноценный сервис необходимо использовать функцию `msrc.SimpleService`.
94Она обернет такой сервис в стандартную реализацию, которая позволит отслеживать Liveness Probe
95на основе статуса работы сервиса, а так же останавливать его при помощи встроенного контекста,
96который будет переключаться на `<-ctx.Done()` при завершении работы.
97
98Данный функционал позволяет так же реализовывать правильную остановку, если ваш сервис не поддерживает
99остановку через контекст.
100
101В качестве последнего аргумента можно передать таймаут ожидания завершения работы функции.
102Логика работы следующая: либо сервис завершает работу за это время, либо разблокируем остановку,
103чтоб не ожидать дольше положенного времени. По умолчанию данный интервал ожидания - 5 секунд.
104
105Если передать в качестве интервала ожидания 0, то таймаут ожидания составит 1000 часов, что
106по сути эквивалентно ожиданию реальной остановки сервиса.
107
108## HTTP сервер
109
110В библиотеку включена поставка стандартного HTTP сервера в виде обертки для Multi Service.
111Данная обертка принимает на вход хост и порт для HTTP сервера, а так же роутер, который
112необходимо использовать для сервера. Роутер должен реализовывать стандартный интерфейс
113`http.Handler`.
114
115Данный сервис так же позволяет переопределять стандартные параметры сервера. Для этого
116необходимо передать переопределение в качестве последнего аргумента фабрики.
117
118```go
119// HttpService реализует фабрику сервиса для библиотеки, реализующего
120// функционал HTTP сервера. На вход передаются обязательные аргументы
121// для HTTP сервера, а так же возможна передача конфигурации запуска
122// сервера.
123//
124// Если конфигурация запуска не передана, то будет использоваться конфигурация
125// `http.Server{}`, при этом в обоих случаях (передано/не передано) будет
126// происходить переопределение полей Addr и Handler в соответствии с
127// переданными обязательными аргументами функции.
128func HttpService(
129HttpHost, HttpPort string,
130Router http.Handler,
131GraceStopPeriodSeconds uint8,
132ServerConfig ...*http.Server,
133) ServiceInterface
134```
135
136## Реализация Liveness для Kubernetes
137
138Для реализации данного функционала у каждого сервиса предусмотрено 2 метода:
139```go
140// Возвращает статус состояния запуска сервиса
141IsStarted() bool
142
143// Возвращает статус сервиса: живой или нет
144IsAlive() bool
145```
146
147Первый возвращает статус **запуска сервера**. Используется для `Readyness Probe`
148
149Второй возвращает статус: **жив ли сервис**. Используется для `Liveness Probe`
150
151По сути статусы всех сервисов суммируются и выдается итоговый результат как для `readyness`,
152так и для `liveness`, поэтому если хотябы один сервис умрет, то `liveness` не пройдут и будет
153вызвана остановка пода.
154
155Для настройки Kubernetes необходимо при инициализации сервиса передать порт прослушивания liveness:
156```go
157service := multiservice.MultiService(
158map[string]multiservice.ServiceInterface{
159"Test-Service": &service{},
160},
16119000
162)
163```
164
165Если передано значение 0, то liveness не будет подключен. По умолчанию данный аргумент можно не передавать.
166
167Для проверки используйте следующие url контейнера:
168```
169/ready - Readyness Probe
170/alive - Liveness Probe
171```