msrc

1
Унаследовано от "gitlab.systems-fd.com/packages/golang/servers/msrc/v3
2

3
# Библиотека мультисервисного приложения для `Golang`
4

5
Библиотека предназначена для реализации мультисервисных приложений на `Golang`.
6
Например: У вас есть сервис, который предоставляет RestAPI, а также требуется реализация
7
Websocket. По сути каждый сервис требует блокировки основной `Go-routine`, можно использовать
8
дочерние `go-routine`, что по сути и делает эта библиотека.
9
Также библиотека реализует `Graceful shutdown`, который позволит правильно останавливать сервисы.
10
Сервис поддерживает логирование на основе `github.com/sirupsen/logrus`
11

12
## Установка
13

14
Необходимо включить библиотеку в один из скриптов следующим образом:
15
```go
16
import "gitlab.systems-fd.com/packages/golang/servers/msrc/v3"
17
```
18

19
Далее необходимо установить зависимости при помощи стандартной утилиты `go get`:
20
```bash
21
go get -u gitlab.systems-fd.com/packages/golang/servers/msrc/v3
22
```
23
                  
24
## Использование
25

26
Для использования библиотеки необходимо реализовать интерфейс сервиса:
27
```go
28
// ServiceInterface описывает интерфейс сервиса, для параллельного запуска.
29
type ServiceInterface interface {
30
	// Run выполняет запуск сервера
31
	Run() error
32

33
	// GracefulShutdown выполняет правильную остановку сервиса
34
	GracefulShutdown()
35

36
	// IsStarted возвращает статус состояния запуска сервиса
37
	IsStarted() bool
38

39
	// IsAlive возвращает статус сервиса: живой или нет
40
	IsAlive() bool
41
}
42
```
43

44
Далее необходимо использовать фабрику для генерации объекта службы:
45
```go
46
service := msrc.MultiService(
47
    map[string]multiservice.ServiceInterface{
48
        "Test-Service": &service{},
49
    },
50
)
51
```
52

53
При передаче списка, ключ используется в качестве уникального названия сервиса.
54

55
После создания объекта сервиса необходимо его запустить:
56
```go
57
err := service.Run()
58
```
59

60
В случае возникновения ошибки сервис остановит все подсервисы с использованием `Graceful shutdown`
61
и вернет возникшую ошибку.
62

63
## Укороченный интерфейс сервиса
64

65
В библиотеку включена реализация функционала отслеживания статуса остановки и завершения
66
на основе контекста. Данный функционал входит в реализацию `msrc.SimpleService`
67

68
Данный сервис принимает на вход сервис с интерфейсом:
69
```go
70
// SimpleService описывает интерфейс упрощенного сервиса, для библиотеки.
71
// Данный сервис может быть использован в случаях, когда нет необходимости
72
// внутри следить за флагами состояния. Сервис должен реализовывать лишь
73
// функционал работы и правильной остановки.
74
type SimpleService interface {
75
	// Run выполняет запуск упрощенной версии сервиса.
76
	// На вход передается контекст, который передаст `<-ctx.Done()` в случае
77
	// его остановки. Сам сервис должен обрабатывать его, если он не реализует
78
	// своего собственного, отдельного алгоритма остановки.
79
	Run(ctx context.Context) error
80

81
	// GracefulShutdown выполняет правильную остановку упрощенного
82
	// сервиса. В данном случае, если сервис необходимо останавливать
83
	// вызовом отдельного функционала остановки, этот метод предоставляет
84
	// такую возможность.
85
	//
86
	// Метод вызывается в процессе остановки сервера и принимает на вход
87
	// контекст с deadline, устанавливаемым сверху. За установленное время
88
	// сервис либо завершает работу, либо отключается принудительно.
89
	GracefulShutdown(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
// переданными обязательными аргументами функции.
128
func HttpService(
129
	HttpHost, HttpPort string,
130
	Router http.Handler,
131
	GraceStopPeriodSeconds uint8,
132
	ServerConfig ...*http.Server,
133
) ServiceInterface
134
```
135

136
## Реализация Liveness для Kubernetes
137

138
Для реализации данного функционала у каждого сервиса предусмотрено 2 метода:
139
```go
140
// Возвращает статус состояния запуска сервиса
141
IsStarted() bool
142

143
// Возвращает статус сервиса: живой или нет
144
IsAlive() bool
145
```
146

147
Первый возвращает статус **запуска сервера**. Используется для `Readyness Probe`
148

149
Второй возвращает статус: **жив ли сервис**. Используется для `Liveness Probe`
150

151
По сути статусы всех сервисов суммируются и выдается итоговый результат как для `readyness`,
152
так и для `liveness`, поэтому если хотябы один сервис умрет, то `liveness` не пройдут и будет
153
вызвана остановка пода.
154

155
Для настройки Kubernetes необходимо при инициализации сервиса передать порт прослушивания liveness:
156
```go
157
service := multiservice.MultiService(
158
    map[string]multiservice.ServiceInterface{
159
        "Test-Service": &service{},
160
    },
161
    19000
162
)
163
```
164

165
Если передано значение 0, то liveness не будет подключен. По умолчанию данный аргумент можно не передавать.
166

167
Для проверки используйте следующие url контейнера:
168
```
169
/ready - Readyness Probe
170
/alive - Liveness Probe
171
```