Введение

Начиная с macOS 12.3 Apple наконец-то предоставляет новую возможность для создания  виртуальной веб-камеры - с помощью Camera Extension. Это такой новый тип системных расширений (System Extensions) - механизма, появившегося в macOS 10.15 (Catalina). Системные расширения призваны заменить расширения ядра (Kernel Extensions, KEXTs), выполняя те же самые функции по расширению возможностей macOS на низком уровне, но при этом работая в пространстве пользователя (user space). Camera Extensions также были созданы для замены старого механизма создания виртуальных камер - через плагины CoreMedia I/O DAL Plug-ins. Одним из главных недостатков этих плагинов является то, что они, как и любой плагин, должны загружаться в каждый процесс (клиентского приложения), который хочет использовать камеру, представляемую этим плагином. С этой загрузкой в последнее время начали возникать проблемы из-за различных мер по обеспечению безопасности, которые Apple стала планомерно внедрять в свою ОС. Но даже когда ограничения позволяют загрузить сторонний плагин в процесс клиентского приложения, если в этом приложении включён sandboxing, то плагин становится полностью изолированным и не может получать исходные данные для камеры откуда бы ни было. Именно эти недостатки и призван преодолеть Camera Extension, который запускается системой в своём собственном процессе, а его взаимодействие и отправку видеоданных клиентским приложениям ОС также берёт на себя.

В 32-минутном ролике сотрудник Apple лихо демонстрирует, как создать такое расширение, а также приложение, которое передает в него некие данные. Само расширение создается из шаблона, нужно подправить пару деталей и вуаля - все готово. Конечно же, на самом деле все гораздо сложней. Кроме того, что опущены различные детали безопасности, без которых ничего не заработает, сам механизм передачи данных рассмотрен настолько бегло, что можно говорить о том, что он практически не документирован.

Итак, у нас есть рабочий прототип системного расширения с камерой, осталось приделать к нему передачу видео потока и управляющих сигналов из нашего приложения. Естественным решением выглядит использование XPC - механизма межпроцессной коммуникации. Все указывает на то, что по аналогии с другой технологией виртуальной камеры (DAL) нужно соединяться через XPC с сервисом Mach Service, в роли которого выступает наш Camera Extension. Для создания такого XPC-соединения в Objective-C классе NSXPCConnection есть метод initWithMachServiceName:. Но выяснилось, что установить такое XPC-соединение невозможно, по крайней мере, обычным способом, без использования хаков. Скорее всего, это связано с тем, что процесс Camera Extension запускается под другим юзером (_cmiodalassistants) и поэтому не виден из процесса нашего приложения. Во всяком случае, при попытке установить соединение (вызов метода remoteObjectProxyWithErrorHandler: у объекта NSXPCConnection) получаем ошибку с кодом 4099 из NSCocoaErrorDomain ("Couldn’t communicate with a helper application."), с описанием:                                                                                      

{
    NSDebugDescription = "The connection to service named
        XXXXXXXXX.com.company.appName.cameraExtension was invalidated: failed at 
        lookup with error 3 - No such process.";
}

Как выясняется, XPC-соединения - не тот способ, которыми можно обмениваться данными между приложением и Camera Extension. Именно такие рекомендации дают на девелоперском форуме Apple: https://developer.apple.com/forums/thread/706184?answerId=723807022#723807022. Вместо них для передачи кадров в Camera Extension предлагают использовать sink stream, т.е. объявить в виртуальной камере возможность ввода данных в неё. Давайте реализуем этот вариант.

Входной поток (Sink Stream)

Отличие создания объекта sink stream от source stream это указание направления этого потока CMIOExtensionStreamDirectionSink. В расширении:

stream = [[CMIOExtensionStream alloc] 
    initWithLocalizedName:localizedName 
    streamID:streamID 
    direction:CMIOExtensionStreamDirectionSink
    clockType:CMIOExtensionStreamClockTypeHostTime
    source:self];

Затем созданный экземпляр объекта добавляется как второй stream в объект CMIOExtensionDevice по аналогии с Source Stream

[device addStream:stream error:&error]

Теперь давайте разберемся, как подключиться к расширению из приложения.

Для того, чтобы подключиться к запущенному расширению для передачи стрима и чтения/записи его параметров необходимо:

    1. Получить список девайсов и найти нужный нам (например по имени device.localizedName):

auto discoverySession = [AVCaptureDeviceDiscoverySession
    discoverySessionWithDeviceTypes: @[AVCaptureDeviceTypeExternalUnknown]
    mediaType: AVMediaTypeVideo
    position: AVCaptureDevicePositionUnspecified];
devices = discoverySession.devices;

    2. Получить значение CMIOObjectID по свойству uniqueId класса AVCaptureDevice, для этого получаем список девайсов, но уже используя другое CMIO API:

UInt32 dataSize = 0;
UInt32 dataUsed = 0;
CMIOObjectPropertyAddress opa = {
    CMIOObjectPropertySelector(kCMIOHardwarePropertyDevices),
    CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal),
    CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain)
};

CMIOObjectGetPropertyDataSize(CMIOObjectPropertySelector(kCMIOObjectSystemObject),
    &opa, 0, nil, &dataSize);

auto devicesCount = int(dataSize) / sizeof(CMIOObjectID);
std::vector<CMIOObjectID> devices(devicesCount);

CMIOObjectGetPropertyData(CMIOObjectPropertySelector(kCMIOObjectSystemObject),
    &opa, 0, nil, dataSize, &dataUsed, devices.data());

    3. Найти среди всех девайсов устройство с UID равным uniqueId, из найденного AVCaptureDevice через свойство kCMIODevicePropertyDeviceUID:

opa.mSelector = CMIOObjectPropertySelector(kCMIODevicePropertyDeviceUID);
CMIOObjectGetPropertyDataSize(devices[deviceObjectIndex],
    &opa, 0, nil, &dataSize);

CFStringRef cfUID = NULL;
CMIOObjectGetPropertyData(devices[deviceObjectIndex],
    &opa, 0, nil, dataSize, &dataUsed, &cfUID);

   4. В результате мы имеем значение CMIOObjectID устройства, которое поможет получить доступ к списку его потоков. Для получения списка потоков также необходимо воспользоваться CMIO API по этому device id:

UInt32 dataSize = 0;
UInt32 dataUsed = 0;
CMIOObjectPropertyAddress opa = {
    CMIOObjectPropertySelector(kCMIODevicePropertyStreams),
    CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal),
    CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain)
};

CMIOObjectGetPropertyDataSize(deviceId, &opa, 0, nil, &dataSize);

int streamsCount = int(dataSize) / sizeof(CMIOStreamID);
std::vector<CMIOStreamID> streamIds(streamsCount);

CMIOObjectGetPropertyData(deviceId, &opa, 0, nil, dataSize, 
    &dataUsed, streamIds.data());

  В случае успеха этих операций у нас будет список потоков, зарегистрированных в расширении. Мы выбираем поток, работающий в направлении CMIOExtensionStreamDirectionSink - он был добавлен вторым. Значение CMIOStreamID как раз таки и характеризует этот поток. Далее необходимо просто начать поток следующим методом:

OSStatus CMIODeviceStartStream(CMIODeviceID  deviceID, CMIOStreamID streamID)

Однако простого создания потока будет мало, так как мы хотим отправлять в него видео, мы должны создать объект CMSimpleQueue методом CMSimpleQueueCreate, а также "привязать" эту очередь к самому потоку методом CMIOStreamCopyBufferQueue

CMSimpleQueueCreate(kCFAllocatorDefault, 5, &sinkQueue);

CMIODeviceStreamQueueAlteredProc handler 
    = [](CMIOStreamID streamID, void* token, void* refCon) {
            auto self = static_cast<TSClassName*>(refCon);
            self->_readyToEnqueue = true;
    };

CMIOStreamCopyBufferQueue(sinkStream, handler, this, &sinkQueue);

Где sinkQueue определена как поле класса типа CMSimpleQueueRef. В дальнейшем это поле используется для отправки изображения в этот поток методом CMSimpleQueueEnqueue.

Пользовательские свойства (Custom Properties)

Другой способ передачи данных - custom properties. Мы использовали эти свойства для передачи управляющей информации, то есть небольших (относительно видео) объемов данных. Использование свойств для передачи видео-потока представляется возможным, но не исследовалось на предмет производительности.

Добавить свойство можно в любой из объектов, CMIOExtensionDeviceSource или CMIOExtensionStreamSource, но давайте сделаем это в устройство. Просто добавим несколько новых строк в нужном формате в уже существующий метод availableProperties.

@implementation DeviceSource

- (NSSet<CMIOExtensionProperty> *)availableProperties
{
    return [NSSet setWithObjects:
        	CMIOExtensionPropertyDeviceTransportType,
        	CMIOExtensionPropertyDeviceModel,
        	@"4cc_clie_glob_0000", // кастомное свойство, положите в константу
        	@"4cc_reso_glob_0000", // кастомное свойство
        	nil];
}

Мы добавили 2 новых свойства, clie - clients (список клиентов), reso - resolution. Имя свойства задается в формате: 4cc_selector_scope_element. Где “4cc” константа, затем 4-хзначный селектор (4сс == 4 character code), затем scope и element, все разделены подчеркиванием. В наших примерах мы всегда будем использовать scope = global, а element 0000, что значит main, но можно использовать любое число. Таким образом, мы будем задавать разные свойства, меняя только 4х-символьный селектор.

Добавленные таким образом свойства будут доступны из приложения посредством такой структуры:

CMIOObjectPropertyAddress propertyAddress = {
	CMIOObjectPropertySelector(FOUR_CHAR_CODE('clie')), // clie
	CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal), // glob
	CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain) // 0000
};

Где макрос FOUR_CHAR_CODE создаст селектор с нужным 4х-символьным кодом.

Давайте попробуем передать произвольную структуру данных из расширения в приложение. Для обмена удобнее всего объявить в общем для расширения и приложения заголовочном файле структуру, например:

typedef struct TSResolution {
    uint32_t  width;
    uint32_t  height;
} TSResolution;

В существующий метод нашего устройства, добавим отдачу нового свойства:

- (nullable CMIOExtensionDeviceProperties *)
    devicePropertiesForProperties:(NSSet<CMIOExtensionProperty> *)properties
    error:(NSError * _Nullable *)outError
{
    CMIOExtensionDeviceProperties *deviceProperties 
        = [CMIOExtensionDeviceProperties devicePropertiesWithDictionary:@{}];
// …
if ([properties containsObject:@"4cc_reso_glob_0000"]) {
    	TSResolution res = {.width = 1920, .height = 1080};
    	NSData * resData = [NSData dataWithBytes:&res length:sizeof(res)];
    	CMIOExtensionPropertyState* propertyState
           = [CMIOExtensionPropertyState propertyStateWithValue:resData];
    	[deviceProperties setPropertyState:propertyState 
             forProperty:@"4cc_reso_glob_0000"];
}
    return deviceProperties;
}

Как видим, мы просто создаем объект NSData, содержащий копию данных нашей структуры и выставляем этот объект как состояние соответствующего свойства. В качестве данных можно использовать другие объекты, например строки NSString.

Теперь можно прочитать эти данные обратно из приложения. Для этого нужен буфер, например std::vector или NSMutableData. Подключаемся к нашему объекту (см. выше п.2), здесь и далее CMIOObjectID objectID. Пример (проверки пропущены):

CMIOObjectPropertyAddress propertyAddress = {
    CMIOObjectPropertySelector(FOUR_CHAR_CODE('reso')),
    CMIOObjectPropertyScope(kCMIOObjectPropertyScopeGlobal),
    CMIOObjectPropertyElement(kCMIOObjectPropertyElementMain)
};

UInt32 dataSize = 0;
UInt32 dataUsed = 0;
OSStatus status = CMIOObjectGetPropertyDataSize(objectID,
     &propertyAddress, 0, nil, &dataSize);

if (status != 0) {
    return status;
}

std::vector<char> buffer(dataSize);
status = CMIOObjectGetPropertyData(objectID,
    &propertyAddress, 0, nil, dataSize, &dataUsed,
    (void *)buffer.data());

TSResolution * res = (TSResolution *)buffer.data();
// res->width; res->height

Все хорошо, однако мы заметили, что повторный вызов получения данных свойства через CMIOObjectGetPropertyData не приводит к повторному чтению данных из метода devicePropertiesForProperties. Нам просто вернутся те же самые данные, что и при первом вызове, а сам вызов не дойдет до нашего кода. Дело в том, что если данные кастомного свойства поменялись, то мы должны явно об этом уведомить.

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

CMIOObjectSetPropertyData(objectID,
    &propertyAddress,
    0,
    nil,
    dataSize,
    (void *)buffer.data());
// CMIOObjectGetPropertyData // потом читаем

При этом в расширении саму операцию записи можно игнорировать, просто уведомлять об изменении:

- (BOOL)setDeviceProperties:(CMIOExtensionDeviceProperties *)deviceProperties error:(NSError * _Nullable *)outError
{
    NSDictionary<CMIOExtensionProperty, CMIOExtensionPropertyState *>* dictionary
        = [deviceProperties propertiesDictionary];
    [self.device notifyPropertiesChanged:dictionary]; // уведомляем об изменении

    return YES;
}

Теперь перед чтением мы будем сбрасывать кеш значения и каждый раз получать новое состояние.

Однако, если нам все же нужно прочитать переданное значение из приложения? То в расширении в метод setDeviceProperties можно добавить:

CMIOExtensionPropertyState* resProperty
    = [dictionary objectForKey:@"4cc_reso_glob_0000"];
if (resProperty && resProperty.value) {
    NSData * resData = (NSData *)resProperty.value;
    TSResolution * res = (TSResolution *)[resData bytes];
}

Передача строки осуществляется несколько проще. В расширении:

CMIOExtensionPropertyState* propertyState 
    = [CMIOExtensionPropertyState propertyStateWithValue:@"String"];
[deviceProperties 
    setPropertyState:propertyState 
    forProperty:@"4cc_prop_glob_0000"];

В приложении:

UInt32 dataSize = 0;
UInt32 dataUsed = 0;
CFStringRef cfStrData = NULL;

CMIOObjectGetPropertyDataSize(objectID,
    &propertyAddress, 0, nil, &dataSize);

CMIOObjectGetPropertyData(objectID,
    &propertyAddress, 0, nil, dataSize, &dataUsed, &cfStrData);

NSString * data = (__bridge NSString *)cfStrData;

В связи с массовым переходом систем, разрабатываемых и поддерживаемых ТомскСофтом, как, например Camfrog, на микросервисную архитектуру необходим инструмент, который позволит сделать этот переход плавным и безболезненным, не прерывая текущую их работу. Кроме того, так как интеграция микросервисов, как правило, осуществляется с помощью вспомогательных систем, таких как, например, брокер сообщений, а изначально монолитная система функционирует, скажем, на HTTP, то этот инструмент должен обеспечить надёжную и стабильную коммуникацию между сервисами, работающими на разных протоколах, будь то сеансовых или с динамической маршрутизацией.

Что такое NATter и зачем он нужен?

NATter – это система с открытым кодом, разрабатываемая ТомскСофтом и написанная на языке Golang, задача которой – проксировать сообщения, между брокером и веб-сайтом. Смысл в том, что новоиспечённый микросервис декомпозируемой монолитной системы использует, например, NATS для обмена сообщениями, а сама система, делегировавшая какую-то часть функционала этому сервису, использует HTTP, что затрудняет коммуникацию между ними. Задача NATter’а как раз и состоит в том, чтобы возобновить общение между монолитом и отколовшимся от микросервисом.

Пример использования

Допустим, клиентам какой-либо системы нужно проверять валидность email’а при регистрации или его изменении. Один из способов реализации – это валидация непосредственно на веб-сервере.

Другой способ основан на микросерверном подоходе к архитектуре: выделяется отдельный сервис, занимающийся валидацией email’а и работающий, например, с NATS. Так как запросы продолжают приходить на веб, то возникает проблема его коммуникации с сервисом.

NATter в данном случае с одной стороны предоставляет HTTP-интерфейс для веба, с другой – имеет доступ к очереди сообщений, по ту сторону которой находится сервис, производящий валидацию email’а. Кто именно в конечном итоге обработает запрос и вернёт ответ, для NATter’а и, следовательно, для веба не имеет значения.

Таким образом можно задавать NATter'у неограниченное количество маршрутов, являющихся связующим звеном между вебом и микросервисами.

Хотя NATter и был создан для использования в веб-разработке, ему можно найти и другие применения.

Батчинг

NATter поддерживает отправку сообщений пакетами, то есть каждый отдельный маршрут возможно настроить таким образом, чтобы каждое новое сообщение, пришедшее от отправителя, отдавалось получателю не сразу, а при условиях, определяемых параметрами, такими как таймаут и размер пакета, измеряемый в количестве сообщений. Для сериализации используется Protocol Buffers. Общий алгоритм работы батчинга:

1. заводится таймер, обнуляется счётчик сообщений, определяющий размер пакета, и ожидается приход очередного сообщения;
2. от отправителя приходит сообщение, которое удерживается в памяти до тех пор пока не выполнится одно из следующих условий:
   • таймер истёк;
   • размер пакета достиг определённого максимума;
   • сервис завершает работу;
3. после выполнения одного из условий выше каждое удерживаемое сообщение конвертируется в google.protobuf.Any, после чего массив полученных структур сериализуется в бинарник, отправляемый получателю;
4. если сервис не завершает работу, возврат к шагу 1.

Архитектура

Основой NATter’а является пакет driver, предоставляющий интерфейсы для работы с протоколом:

type Conn interface {
        Serve(context.Context) error
        Close() error
        Receiver(*entity.Route) Receiver
        Sender(*entity.Route) Sender
}

type Receiver interface {
        Listen(Sender) error
        ListenRequest(Sender) error
}

type Sender interface {
        Send(payload []byte) error
        Request(payload []byte) ([]byte, error)
}

Эти интерфейсы в совокупности реализуют шаблон проектирования "Абстрактная фабрика". Conn представляет собой соединение по протоколу, которое можно контролировать с помощью основных методов Serve() и Close(). Также есть два вспомогательных фабричных метода: Receiver() и Sender() – создающих и возвращающих сущности соответственно для приёма и отправки сообщений по протоколу, определяемому сущностью Conn. Настройка получателя и отправителя осуществляется на основе экземпляра структуры entity.Route, передаваемой в фабричный метод:

type Route struct {
        Mode     RouteMode
        Async    bool
        Topic    string
        Endpoint string
        URI      string
}

Здесь Mode – это режим маршрута вида “отправитель-получатель-направленность”, Async – флаг асинхронности маршрута, Topic – топик-источник или топик-назначение сообщения, Endpoint – адрес-назначение сообщения, URI – путь-источник сообщения.

Поле Mode имеет вид “отправитель-получатель-направленность”, где отправитель – это имя протокола-источника сообщения, получатель – имя протокола-назначения сообщения, а направленность – одно из двух значений: oneway (запрос) и twoway (запрос-ответ). Например, http-broker-oneway означает одностороннее проксирование сообщения от HTTP-клиента к брокеру сообщений, а broker-http-twoway – проксирование запроса от брокера к HTTP-серверу и обратное проксирование ответа.

Сами интерфейсы Receiver и Sender предоставляют методы как для односторонней обработки сообщений (Listen() и Send()), так и для обработки запросов-ответов(ListenRequest() и Request()). При этом Receiver требует передачи Sender в свои методы, так как после приёма сообщения Receiver’ом оно сразу направляется Sender’у.

Простой пример использования интерфейсов для создания маршрута:

var (
        httpConn driver.Conn = // ...
        natsConn driver.Conn = // ...
)

route := &entity.Route{
        Topic:    "hello",
        Endpoint: "https://www.world.com/",
}

natsReceiver := natsConn.Receiver(route)
httpSender := httpConn.Sender(route)

natsReceiver.Listen(httpSender)

ctx, _ := context.WithTimeout(context.Background(), time.Minute)

go func() {
        httpConn.Serve(ctx)
        httpConn.Close()
}

go func() {
        natsConn.Serve(ctx)
        natsConn.Close()
}

<-ctx.Done()

В данном примере создаются сущности Conn, относящиеся к протоколам “HTTP” (httpConn) и “NATS” (natsConn). После этого создаются natsReceiver (с топиком hello) и httpSender (с адресом https://www.world.com/). Строка

natsReceiver.Listen(httpSender)

буквально означает следующее: “отправить сообщение, принятое natsReceiver’ом (т.е. из топика hello), httpSender’у (т.е. по адресу https://www.world.com/)”. Далее httpConn и natsConn приводятся в готовность вызовом блокирующего метода Serve() и закрываются по завершении контекста ctx вызовом Close().

Регистрация маршрутов, описанная выше в общих чертах, выполняется сущностью service.Router. Конструктор Router’а принимает массив маршрутов и карту <string, driver.Conn>, где string – это имя соединения; эта карта при обработке режима маршрута (entity.Route.Mode), указываемого в конфиге, позволяет определить, по каким именно протоколам требуются соединения для регистрации маршрута. Например, если имеется следующая карта:

map[string]driver.Conn{
        "nats":      natsConn,
        "kafka":     kafkaConn,
        "websocket": websocketConn,
}

то поле Route.Mode может быть nats-websocket-oneway, kafka-nats-oneway, websocket-kafka-twoway и т.д.

Инициализация соединений и создание на их основе карты осуществляется в методе (*cmd.NATter) setupConns() error.

Выпуск в open source

Изначально проект разрабатывался только для внутреннего использования и назывался (и, по крайней мере, пока продолжает называться внутри ТомскСофта) “NATter v2.0”. Название было унаследовано от менее универсальной системы “NATter”, ныне уже не используемой, на которой и основана данная разработка. Решение о выпуске проекта в open source поставило перед нами задачу разработать такую архитектуру, которая позволит дополнять функционал NATter'а собственными реализациями работы с протоколами помимо тех, что уже “вшиты” в базовую реализацию сервиса (HTTP, NATS, Kafka), не изменяя заложенную концепцию, а также “вытянуть” все зависимости из нашей общей библиотеки, написанной специально для сервисов Camshare, непосредственно в NATter.

Используемые библиотеки

Реализация необходимых модулей внутренней библиотеки для сервисов Camshare была вытянута в почти неизменном виде, а значит, что и внешние Go-библиотеки для реализации и модульного тестирования были взяты те же, что и в нашем самописном фреймворке. Упоминания стоят следующие библиотеки, фундаментально повлиявшие на ход разработки как Camshare-сервисов в целом, так и NATter’а в частности:

• nats-io/nats.go – клиент, используемый для реализации работы с NATS;
• Shopify/sarama – клиент, используемый для реализации работы с Apache Kafka;
• go-chi/chi – HTTP-роутер, используемый для реализации REST API;
• golang/protobuf – библиотека для работы с Protocol Buffers, используемая для сериализации сообщений в пакеты;
• stretchr/testify – библиотека, предоставляющая инструменты для тестирования кода: assert’ы, mock’и, suite’ы.

Несмотря на то что модули внутренней библиотеки уже были готовы к использованию, их перенос непосредственно в исходный код NATter’а требовал склеивания логики пакетов из библиотеки, реализующих работу с протоколами, с логикой соответствующих пакетов в самом сервисе во избежание наличия лишних уровней абстракции.

Заключение

NATter позволяет относительно легко интегрировать системы, работающие с разными сетевыми протоколами, что очень полезно при перестройке проектов на микросервисную архитектуру, когда отдельные сервисы разрабатываются постепенно и требуют интеграции по мере своей готовности.

Исходный код NATter’а уже загружен в публичный репозиторий, и в скором времени ожидается первый релиз.

Иногда случается так, что в рамках разработки программного продукта становится очевидно, что часть его функционала самодостаточна и может распространяться отдельно. В этот момент появляется необходимость создания SDK инкапсулирующего в себе отдельные технологические наработки. В контексте разработки на языке C++, решение этой задачи часто приводит к появлению динамической библиотеки, предоставляющей доступ к реализации определенных функциональных возможностей, и распространяющейся как отдельный продукт. В этой статье мы рассмотрим тонкости реализации описанного сценария.

О библиотеках и местах их обитания

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

Статические библиотеки

Статические библиотеки по своей сути являются самым прямым воплощением идеи библиотек. В процессе сборки компилятор, проходя по всем файлам проекта, создает объектные файлы, содержащие код и данные для каждой единицы трансляции. Статические библиотеки появились из идеи, что можно разделять код путем повторного использования общих объектных файлов. Такие библиотеки иногда называют «архивами», поскольку фактически это просто набор упакованных объектных файлов. Так в UNIX-подобных операционных системах они обладают расширением *.a от слова archive. В Windows статические библиотеки обычно имеют расширение *.lib, хотя такое же расширение можно заметить и у файлов с информацией об экспортируемых символах динамических библиотек, что вносит некоторую путаницу.

В процессе сборки программы компоновщик объединяет переданные ему компилятором объектные файлы, ведя список символов, для которых пока не нашлось части кода с реализацией. Когда предоставленный ему компилятором перечень объектных файлов заканчивается, компоновщик начинает поиск недостающих символов в переданных на линковку библиотеках. Если еще не определенный символ находится в одном из объектов статической библиотеки, тогда этот объект добавляется к исполняемому файлу. Следует обратить внимание на то, что найденный объектный файл добавляется в программу целиком, что может повлечь за собой пополнение списка неразрешенных символов. Процесс сопоставления символа и кода его реализации на этапе компиляции также называется ранним связыванием.

Преимуществом использования статических библиотек является простота распространения приложения - на выходе получается один исполняемый файл с нужным кодом внутри. Причем, в процессе линковки из статической библиотеки будут подключены только те объектные файлы, код либо данные которых используются в приложении.

Однако, использование статических библиотек налагает на разработчиков определенные ограничения, часто не подходящие для реализации SDK. В том числе:

1. При обновлении версии библиотеки необходима перекомпиляция приложения.
2. Статическая библиотека, написанная на C++, не может свободно распространяться в виде скомпилированного файла из-за проблемы отсутствия стандартизированного ABI (о чем будет рассказано ниже). Распространение библиотеки в виде исходных файлов не всегда желательно.
3. Поскольку код статической библиотеки включается напрямую в исполняемый файл, он не может быть разделен с другими приложениями, использующими ту же библиотеку. Это может приводить к ситуациям, когда один и тот же код загружается в память многократно.

Динамические библиотеки

Развитием идеи разделения общего кода между независимыми приложениями стало появление динамических библиотек. Например, реализация системных либо широко используемых библиотек, таких как стандартная библиотека C++, в виде статических библиотек чрезвычайно накладна — массовое дублирование одинаковых частей кода среди всех приложений в системе привело бы к сокращению доступного дискового пространства и оперативной памяти. Кроме того, необходимость исправления реализации одной из функций в такой библиотеке означала бы неизбежную пересборку всех зависимых приложений.

Динамические библиотеки спроектированы для решения таких проблем. Обычно они имеют расширение *.dll в Windows, *.so в UNIX, *.dylib в macOS. В процессе сборки программы компоновщик, обнаруживая символ из разделяемой библиотеки, не включает его определение в исполняемый файл. Вместо этого, фиксируется имя символа и библиотеки, в которой он должен быть реализован. При работе процесса, операционная система просматривает список зависимостей, подгружая в память либо используя уже загруженный код нужных динамических библиотек. Разрешение символов в процессе работы приложения называется поздним связыванием.

Это означает, что ни один исполняемый файл, зависящий от динамической библиотеки, не содержит объектных файлов с кодом этой библиотеки. При необходимости обновить или исправить реализацию, например, функции, предоставляемой библиотекой, необходимо заменить лишь файл библиотеки без перекомпиляции зависимых приложений.

Другие преимущества использования динамических библиотек:

1. Экономия как дисковой, так и оперативной памяти за счет использования одного и того же кода.
2. Доступ к общим ресурсам, разделяемым между всеми приложениями (строки, константы, изображения).
3. Ускорение сборки приложения. Нет необходимости включать код динамической библиотеки в исполняемый файл.

Основные недостатки:

1. Появляется необходимость поддержки обратной совместимости и версионирования библиотек.
2. Необходимость предоставлять динамические библиотеки при развертывании приложения. Приложение не запустится, если в системе нет нужной библиотеки.
3. Многочисленные проблемы связности библиотек, которые иногда обобщенно называют Dependency Hell. Зачастую проявляются в виде перекрестных зависимостей от разных версий одной и той же библиотеки.

Есть два способа подключения динамических библиотек к пользовательскому приложению:

1. Динамическая линковка
2. Динамическая загрузка

При динамической линковке библиотека инициализируется в момент старта процесса. Всю работу по сопоставлению символов с адресами в памяти берет на себя операционная система, а точнее специальная программа-загрузчик.

В случае динамической загрузки процесс во время своей работы явно вызывает загрузку библиотеки при помощи вызовов API операционной системы, таких как LoadLibrary() в Windows и dlopen() в Unix. В этом случае не происходит автоматического связывания символов с фактическими адресами в коде загруженной библиотеки. Процесс должен сам осуществить поиск нужного символа в памяти при помощи таких функций как GetProcAddress() или dlsym().

Динамическая загрузка — повторяющийся паттерн в приложениях, которые поддерживают плагинную систему.

Плагины

По своей сути плагины являются технологией, позволяющий в определенных пределах изменять функциональные возможности приложения без необходимости внесения изменений в его программный код. Например, практически все современные веб-браузеры используют плагины для реализации поддержки разных форматов мультимедии, в том числе видео, аудио и графических изображений. Поскольку при динамической загрузке библиотеки нет необходимости ее наличия на этапе компиляции, а интерфейс плагина может быть стандартизирован, становится достаточно легко создать подсистему приложения, которая была бы способна подключать любое количество динамических библиотек из определенного каталога, реализующих дополнительную функциональность.

На этом этапе мы подходим к двум важным темам — программный и двоичный интерфейс приложений, называемые так же API и ABI.

Об API, ABI и языке C

Чтобы понять, как наши библиотеки взаимодействуют с кодом пользовательского приложения, нужно разобраться, что такое API и ABI.

API - Application Programing Interface

В широком смысле API – это протокол, который описывает, как можно использовать данный программный код. В контексте C++ API – это набор публичных типов, функций, переменных, открытых для внешнего кода из приложения или библиотеки. Вместе с библиотекой обычно поставляется заголовочные файлы *.h, которые и являются описанием её API.

ABI - Application Binary Interface

В C++ под термином ABI понимают детали реализации языковых конструкций на двоичном уровне, не специфицированных в стандарте языка. Стандарт C++ описывает общую модель языка, но не указывает на то, какие подходы использовать для её реализации. В качестве примера можно привести виртуальные функции. В стандарте есть описание того, какое поведение ожидается от виртуальных функций, но нет информации о том, как его реализовать. Расположение классов и их виртуальных таблиц в памяти, способ передачи параметров в функции (через стек или регистр), реализация возврата значения из функции, механизм исключений — все это описывается в ABI. Если два компилятора на одной платформе реализуют разные ABI, то их код будет несовместим на бинарном уровне. Иногда ABI изменяется даже между разными версиями одного компилятора.

Name Mangling

Стоит отдельно упомянуть такую особенность ABI, как Name Mangling. Методы и данные в приложениях на языке C++ имеют внутренние или декорированные имена, отличные от их имен в исходном коде. Декорированное имя — это символьная строка, в которой вместе с именем объекта закодирована дополнительная информация о типе, параметрах, соглашении о вызовах и других полезных для компилятора подсказках, помогающих найти правильный код функции.

Поскольку для языка C++ нет общепринятого ABI, при динамической загрузке библиотеки может возникнуть проблема поиска нужных символов из-за декорирования имен. Однако здесь на помощь приходит язык C. Директива препроцессора extern "C" позволяет отключить декорирование имени для экспортируемых интерфейсов библиотеки, так как если бы они были написаны на C.

Пример Name Mangling:

Calling Convention

Чтобы иметь возможность вызвать функцию из нашего SDK не достаточно знать одно лишь её имя. Такие важные особенности работы функций, как способ передачи параметров (через стек или через регистры), порядок их размещения и механизм реализации возвращенаемого значения, могут отличатся между разными компиляторами. В общем случае эти детали объединяют под термином Calling Convention.

К примеру, вот некоторые известные соглашения о вызове функций и их краткое описание:

Заметка об исключениях

Исключения, при их наличии, не должны покидать кода библиотеки. Реализация механизма исключения отличается между компиляторами и так же является частью ABI C++. Если функция в процессе своей работы должна сообщить об ошибке, она должна сделать это через возвращаемое значение.

Об экспортируемых и импортируемых символах

Общие принципы работы разделяемых библиотек одинаковы вне зависимости от платформы (Windows, Linux, macOS). Однако так же существуют и некоторые существенные различия.

Экспортируемые символы

Основное отличие заключается в том факте, что в библиотеках, собранных в UNIX-подобных системах, все символы всех объектных файлов библиотеки экспортируются автоматически, если они не запрещены для экспорта путем использования модификатора static. В Windows символы не экспортируются, если они не открыты для доступа явно.

Существует три способа экспортировать символ из *.dll:

1. При помощи директивы __declspec(dllexport)
2. При помощи опции компоновщика export:symbol
3. При помощи специального *.def файла, содержащего символы для экспортирования.

Импортируемые символы

Кроме необходимости для динамических библиотек в Windows явно определять экспортируемые символы, разрешается так же явно указывать символы, подлежащие импорту в приложении. Это не обязательная процедура, но она указана как способствующая оптимизации скорости работы с DLL.

Распространенный подход решения проблем с экпортом/импортов нужных символов — использование макросов препроцессора. Пример:

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

Дополнительные файлы DLL

Еще один уровень сложности при работе с библиотеками Windows связан с тем фактом, что дополнительная информация о DLL (как, например, информация об экспортируемых символах) хранится в отдельных файлах. Среди них:

• *.lib – файл импорта библиотеки, описывающий какой и где символ хранится в DLL. Создается только если библиотека экспортирует символы. При динамической линковке исполняемый файл, использующий DLL, обращается *.lib файлу для поиска символов.
• *.exp - файл с информацией, необходимой для разрешения циклических зависимостей библиотек.
• *.ilk — файл с информацией о статусе инкрементной компоновки.
• *.def - файл определений, позволяющий управлять деталями скомпонованной библиотеки, включая экспорт символов.
• *.res - файл ресурсов, используемых библиотекой.

В этом DLL отличнается от динамических библиотек в системах UNIX, где вся перечисленная информация обычно добавляется в сам файл библиотеки.

В случае плагинной реализации SDK мы избавляемся от необходимости использования дополнительных зависимостей при помощи динамической загрузки и явного поиска символов.

О стандартном подходе к построению переносимых интерфейсов

Как мы уже успели увидеть, отсутствие общепринятого ABI делает неудобным использование компонентов стандартной библиотеки C++ в открытых интерфейсах. В случае различий в реализации ABI для компилятора, используемого для сборки клиентского приложения, при использовании библиотеки может возникнуть неопределенное поведение.

Классическим подходом к построению переносимых интерфейсов является проектирование API библиотеки при помощи функций и типов языка C. В этом случае при необходимости произведения инициализации/деинициализации библиотеки вызываются соотвествующие функции. Еще одной необязательной особенностью подхода в стиле C является добавление к именам функций префикса, ассоциируемого с названием библиотеки. Это происходит из-за отсутствия возможности реализации namespace без декорирования имен в стиле C++. При необходимости оперирования объектами, создаваемыми библиотекой и хранящими в себе какое-то состояние, используется подход передачи непрозрачного указателя (хендлера) или структуры в вызовы функций из библиотеки.

Пример простого интерфейса:

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

Преимущества и недостатки

К преимуществам использования внешнего интерфейса SDK в стиле C можно отнести следующие пункты:

• Множество современных языков программирования поддерживают работу с библиотеками языка C
• Зависимости от реализации стандартной библиотеки для SDK и клиентского кода разделены. Поскольку выделение и освобождение памяти происходит непосредственно в самом SDK, нет возможности утечек либо неправильного освобождения памяти программы.

В недостатки можно записать следующее:

• Клиентский код сам отвечает за правильную последовательность вызовов функций SDK. Например, если для работы библиотеки необходима первоначальная инициализация, нужная функция должная быть вызвана во внешнем коде. То же самое относится к освобождению ресурсов при окончании работы с библиотекой.
• Необходимо явно вызывать функции создания и удаления объектов.

О расширенном подходе к построению переносимых интерфейсов

Из-за своих ограничений, подход в стиле C при проектировании интерфейса SDK может оказаться недостаточно гибким и удобным, как при работе с объектно-ориентированными компонентами стандартной библиотеки C++. Альтернативой может являться использование интерфейсных классов в составе API.

Интерфейсный класс — это класс, не имеющий данных и состоящий из чисто виртуальных функций. В случае использования интерфейсных классов может быть реализована следующая схема: библиотека предоставляет открытую функцию, которая создает и возвращает указатель на интерфейсный класс-фабрику, с помощью которого создаются экземпляры других классов. В коде библиотеки классы-реализации наследуются от интерфейсов, оставаясь полностью скрытыми и не зависимыми от клиентского кода. В данном подходе необходимо явно объявить только одну точку экспорта — функцию-фабрику. Весть остальной API библиотеки становится доступным за счет таблиц виртуальных функций. Такая схема помогает реализовать гибкие интерфейсы, менее ограниченные, чем при классическом подходе с использованием функций в стиле C. Тут нужно сделать замечание, что использование интерфейсных классов не освобождает от необходимости избегать применения в их методах компонентов стандартной библиотеки C++.

Несмотря на то, что применение интерфейсных классов позволяет использовать преимущества объектно-ориентированного подхода, для корректного проектирования SDK нужно помнить о еще одном важном ограничении: память, выделенная библиотекой под один из своих объектов, должна быть симметрично освобождена при помощи соответствующего кода из библиотеки. Это связано с тем фактом, что реализация работы операторов new() и delete() относится к ABI C++. В общем случае это правило можно сформулировать следующим образом: произведение любых операций в клиентском коде над объектом, созданным библиотекой, безопасно до тех пор, пока эти действия не зависят от реализации стандартной библиотеки.

Таким образом, проблема заключается в необходимости контролировать удаление объектов SDK. Здесь обычно используется один из двух подходов:

1. В интерфейсные классы всех объектов библиотеки добавляется метод для явного удаления объекта (например, release())
2. Указатель на объект должен быть передан специальной функции или методу библиотеки, отвечающей за освобождение памяти соответствующих объектов.

При выборе первого подхода, в клиентском приложении можно избежать дополнительного контроля над освобождением памяти при помощи оборачивания указателей на объекты SDK в умные указатели с указанием функции для освобождения памяти, ссылающейся на методы release().

Почему это работает

Интерфейсный класс, не содержащий в себе данных и функций, представляет собой всего лишь виртуальную таблицу, то есть набор указателей на функции. Этим указателям присваиваются адреса реальных функций из кода библиотеки. Внешний код, работая с интерфейсным классом, вызывает соответствующую имплементацию функции из SDK. Почему такой подход работает для кода всех наиболее значимых компиляторов? Следует напомнить, что таблица виртуальных функций не является единственно возможным вариантом реализации работы виртуальных функций для языка C++.

Ответом является история распространения поддержки технологии COM. Если не вдаваться в детали, спецификация технологии COM хорошо подходила для реализации при помощи таблицы виртуальных функций. Популяризация технологии заставила разработчиков компиляторов добавить её поддержку, сделав использование таблицы виртуальных функций фактически стандартом.

Преимущества и недостатки

Использование интерфейсных классов в SDK дает следующие преимущества:

• Объектно-ориентированный подход к работе с абстракциями SDK.
• При следовании правилу ограничения работы с памятью внутри SDK, библиотека и клиентский код независимы друг от друга и от релизации стандартной библиотеки C++.

Основные недостатки:

• Необходимо тщательно контролировать удаление объектов, созданных библиотекой.
• Методы интерфейсных классов все еще не могут работать со стандартными типами и коллекциями языка С++.

Поддержка бинарной совместимости

В заключении рассмотрим те изменения в коде библиотеки SDK, которые требуют или не требуют пересборку клиентского кода.

Что можно менять в SDK без потери бинарной совместимости с клиентским кодом:

• Добавлять новые функции.
• Добавлять новые виртуальные методы в конец объявления класса, не имеющего наследников.
• Добавлять новые интерфейсные классы.
• Как угодно изменять классы и функции, не являющимися частью API (то есть не экспортируемыми во внешний код).

Какие изменения приведут к перекомпиляции с клиентским приложением:

• Удаление существующих классов и функций, являющихся частью API.
• Удаление существующих виртуальных методов.
• Изменение иерархии интерфейсных классов (добавление или удаление наследования).
• Изменение сигнатуры функций и методов.
• Добавление новых виртуальных методов в середину класса.
• Добавление виртуальных методов в класс, имеющий наследников.

ELK — это аббревиатура из названий трех продуктов: Elasticsearch, Logstash и Kibana.

Logstash — инструмент, который необходим для приема первичных данных из .log файлов и иных представлений. Посредством его работы информацию можно преобразовать и отправить в общее хранилище. В наших примерах и микросервисах данные модифицируются посредство базового кода, поэтому не требовалось использование этого сервиса.  

Elasticsearch — это механизм индексирования и хранения полученной информации, а также полнотекстового поиска по ней. Он является NoSQL решением, главная задача которого — организация быстрого и гибкого поиска по полученным данным. Работа с информацией происходит с помощью REST API, который позволяет добавлять, просматривать, модифицировать и удалять данные.

Можно выделить основное устройство Elasticsearch и провести косвенную аналогию с реляционными бд:

• Индекс - база данных
• Документ - таблица базы данных
• Элемент - запись в таблице

Структуру каждого индекса и содержимое его документов задается с помощью мэппинга.

Kibana — это интерфейс для Elasticsearch, который имеет большое количество возможностей по поиску данных в индексах Elasticsearch и отображению этих данных в удобочитаемых видах таблиц, графиков и диаграмм, карт.

Работа с Elasticseach

Elasticsearch может быть развернут на локальном сервере с помощью системных администраторов или настроен в автоматическом режиме на одном из серверов https://www.elastic.co/

После базовой настройки можно приступить к написанию мэппинга и созданию необходимых индексов.

Эту задачу можно выполнить несколькими путями:

• написание команд из консоли Elasticsearch - документация https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html
• использование php библиотеки для написание собственного API - документация
  https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/installation.html

В данной статьей рассмотрим второй вариант. После установки пакета

composer install elasticsearch/elasticsearch

можно приступить к написанию кода с использованием основ, описанных в документации.

Например, с помощью данного сурдокода будет создан индекс, после чего к нему будет применен описанный мэппинг:

$params = [
    'index' => $index_name
];

$response = $this->es_api->indices()->create($params);

-------------------------------------------------------

$params = [
    'index' => $index_name,
    'body' => [
        'properties' => $properties
    ]
];

return $this->es_api->indices()->putMapping($params);
Мэппинг может быть описан как массив с указанием необходимых полей внутри документа:

Мэппинг может быть описан как массив с указанием необходимых полей внутри документа:

"properties" => [
    "appVersion" =>  [
        "type" => "keyword",
    ],
    "clientApplication" =>  [
        "type" => "keyword",
    ],
    "uid" =>  [
        "type" => "keyword",
    ],
    "ip" =>  [
        "type" => "ip",
    ],
    "usage_date" => [
        "type" => "date",
        "format"  => "yyyy-MM-dd HH:mm:ss"
    ],
    "os" =>  [
        "type" => "keyword",
    ]
]

Таким образом мы создали индекс и описали структуру его документа.
После можно приступить к отправке данных и созданию элементов в elasticsearch.  

Пример кода:

$this->elastic_search
     ->createBulk(ElasticSearch::MAIN_INFO_INDEX, $main_info);
-----------------------------------------------------------------
public function createBulk($index_name, $elements) {

    $params = [];

    foreach ($elements as $element) {
        $params['body'][] = [
            'index' => [
                '_index' => $index_name,
            ]
        ];

        $params['body'][]   = $element;
    }

    if (!empty($params)) {
        try {
            $responses = $this->es_api->bulk($params);
            return $responses;
        } catch (Exception $e) {
            Log::channel("elastic_search_errors")->error("Exception when calling es_api->bulk: ". $e->getMessage());
        }
    }
}

Данные в соответствии с мэппингом будут отправлены в Elasticsearch и готовы для дальнейшей работы с ними.

Введение в работу Kibana

Из личного кабинета https://www.elastic.co/ вы сможете перейти в интерфейс Kibana.
Для создания необходимых визуализаций необходимо привязать сервис к индексам из Elasticsearch.

Для этого из соответствующего раздела настроек потребуется создать индекс-паттерн, который и будет отслеживать механизм Kibana.

В разделе визуализаций возможно построение разных представлений данных.Самое распространенное Lens (содержит множество различных диаграмм и графиков) и Maps (карты и наложенные на них данные).

Интерфейс Kibana дружественен к пользователю и предлагает интуитивно понятное взаимодействие с данными.

В левой части содержится выбранный индекс и структура его документа. Центральная и правая части отводятся для отображения представлений информации и различных форм её агрегирования.

В верхней панели находится строка ввода для написания простых KQL (kibana query language) запросов, которая автоматически подсказывает доступные варианты.

После создания визуализации, её можно сохранить и разместить с другими на одном из дашбордов для удобного просмотра всех представлений данных.

Заключение

Таким образом, посредством изучения документации Elasticsearch PHP API и сервису, написанному с использованием фреймворка Laravel, возможен перенос большого количества данных в систему Elasticsearch, которая представит высокую скорость работы в сравнении с реляционной бд.

Kibana в свою очередь поможет представить информацию в удобном и понятно виде для последующего анализа.

Docker упрощает запуск и развертывание приложений, основой его работы являются образы и виртуальные контейнеры.

Разверните свежее приложение Laravel и настройте его для базовой работы.

Для запуска его в виртуальном контейнере нам потребуется установленный Docker на рабочей машине.

После его установки приступим к настройке.

Dockerfile

Docker позволяет задавать описание настройки среды внутри отдельных контейнеров с помощью файла Dockerfile.

Создайте файл Dockerfile в корне проекта laravel. Данная конфигурация будет использоваться для создания образа приложения, установки всех необходимых зависимостей приложения.

Пример Dockerfile для локальной разработки проекта:

FROM php:7.4-fpm

# Set working directory
WORKDIR /var/www

# Install dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpng-dev \
    libjpeg62-turbo-dev \
    libfreetype6-dev \
    locales \
    zip \
    jpegoptim optipng pngquant gifsicle \
    vim \
    unzip \
    git \
    curl \
    libonig-dev \
    locales \
    nodejs \
    npm \
    zlib1g-dev \
    libicu-dev \
    supervisor \
    g++ \
    --no-install-recommends \
    && rm -r /var/lib/apt/lists/* \
    && sed -i 's/# ru_RU.UTF-8 UTF-8/ru_RU.UTF-8 UTF-8/' /etc/locale.gen \
    && locale-gen

# Clear cache
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# Install extensions
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl intl bcmath gd
RUN docker-php-ext-configure gd --with-freetype=/usr/include/ --with-jpeg=/usr/include/
RUN docker-php-ext-install gd

# Install composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# Install NPM
RUN curl https://www.npmjs.com/install.sh | sh

# Add user for laravel application
RUN groupadd -g 1000 www
RUN useradd -u 1000 -ms /bin/bash -g www www

# Change current user to www
USER www

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

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

Поэтому так же рассмотрим вторую версию.

Пример Dockerfile для развертывания проекта на боевом сервере:

FROM php:7.4-fpm

# Set working directory
WORKDIR /var/www

# Install dependencies
RUN apt-get update && apt-get install -y \
    wget \
    cmake \
    gcc \
    build-essential \
    libpng-dev \
    libjpeg62-turbo-dev \
    libfreetype6-dev \
    locales \
    zip \
    jpegoptim optipng pngquant gifsicle \
    vim \
    unzip \
    git \
    curl \
    libonig-dev \
    locales \
    nodejs \
    npm \
    zlib1g-dev \
    libicu-dev \
    supervisor \
    g++ \
    --no-install-recommends \
    && rm -r /var/lib/apt/lists/* \
    && sed -i 's/# ru_RU.UTF-8 UTF-8/ru_RU.UTF-8 UTF-8/' /etc/locale.gen \
    && locale-gen

# Clear cache
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

# Install extensions
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl intl bcmath gd
RUN docker-php-ext-configure gd --with-freetype=/usr/include/ --with-jpeg=/usr/include/
RUN docker-php-ext-install gd

# Install composer
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# Install NPM
RUN curl https://www.npmjs.com/install.sh | sh

# Add user for laravel application
RUN groupadd -g 1000 www
RUN useradd -u 1000 -ms /bin/bash -g www www

# Copy existing application directory permissions
COPY --chown=www:www . /var/www

RUN npm install && \
    composer install  && \
    composer dumpautoload -o

#laravel cache and optimization
RUN php artisan optimize && \
    php artisan route:cache && \
    php artisan config:cache && \
    php artisan scribe:generate --force

#building frontend assets
RUN npm run development

# Change current user to www
USER www

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]

Данная конфигурация смонтирует образ из базового Docker образа php:7.4-fpm.

Так же установятся указанные пакеты wget, cmake, gcc и прочие. Команда WORKDIR укажет рабочий каталог нашего приложения.

Директива RUN помогает описывать команды, которые должны быть исполнены для установки и настройки различных параметров.

Контейнеры в  Docker по умолчанию запускаются с привилегиями root, поэтому мы создаем пользователя www с ограниченными правами и указываем запуск контейнера от его имени.

Команда EXPOSE открывает порт в контейнере для php-fpm, а CMD указывает команду для запуска сервера.

Docker-compose

Как Dockerfile будет готов, создайте файл  docker-compose.yml с инструкциями для запуска контейнера по образу Dockerfile.

Пример docker-compose.yml:

version: '3.9'
services:
    php:
        build:
           context: .
           dockerfile: Dockerfile
        image: "${ENV}-laravel-app:latest"
        container_name: "${ENV}-laravel-app"
        volumes:
            - laravel-app-volume:/var/www
            - ./storage:/var/www/storage:rw
        command: /bin/bash -c "php artisan migrate --force && php-fpm"
        links:
            - mysql
    mysql:
        image: mysql:latest
        container_name: "${ENV}-laravel-mysql"
        expose:
            - "3306"
        environment:
            - MYSQL_ROOT_PASSWORD
            - MYSQL_DATABASE
            - MYSQL_USER
            - MYSQL_PASSWORD
        volumes:
            - ./mysql:/var/lib/mysql

    nginx:
        image: nginx:latest
        container_name: "${ENV}-laravel-nginx"
        volumes:
            - ./nginx/conf.d:/etc/nginx/conf.d
            - laravel-app-volume:/var/www/
            - ./storage/app/public:/var/www/public/storage:ro
            - ./nginx/logs:/var/log/nginx/
        environment:
            - PROJECT_URL
            - PROJECT_ROOT
            - DIRTY_HACK
            - VIRTUAL_HOST
            - VIRTUAL_PORT
            - LETSENCRYPT_HOST
            - LETSENCRYPT_EMAIL
        expose:
            - $VIRTUAL_PORT
        ports:
            - $VIRTUAL_PORT:$VIRTUAL_PORT

        command: /bin/bash -c "envsubst < /etc/nginx/conf.d/mysite.template > /etc/nginx/conf.d/my.conf && nginx -g 'daemon off;'"
        links:
            - php

volumes:
    laravel-app-volume:
        name: "${ENV}-laravel-app-volume"
        external: false

В приведенном коде задаются базовые элементы, запускаемые внутри контейнеров. Так это сервис nginx, mysql, php и прочее.

В каждом блоке требуется указать необходимую информацию для корректной работы сервисов. Их имена, название образов, из которых будут созданы, конфигурации, а так же связи между разделами контейнеров.

Context параметра build в блоке php сообщает о том, какой каталог относительно docker-compose.yml будет использован как рабочая директория проекта. То есть мы указываем путь до нашего приложения.

Dockerfile указывает название Dockerfile'а, который будет использован для создания образа. Image используется для определения  образа для запуска контейнера, если такой dockerfile не определен или образ по нему уже был смонтирован.

Containername задает имя создаваемого контейнера. Command позволяет запустить указанные команда после запуска контейнера, а links используется для указания алиасов, посредством которых контейнеры могут свободно общаться между друг-другом.

С помощью environment определяются переменные из файла .env, которые будут использоваться при запуске контейнеров.

И, наконец, volumes необходим для создания тома, который обеспечит постоянное сохранения файлов, даже если работа контейнера будет остановлена. А так же указания монтируемого образа, который свяжет наши конфигурационные файлы с сервисами контейнеров.

.ENV

Для работы с динамическими данными, а так же данными, которые должны храниться на сервере и не использоваться внутри Git репозиториев используются переменные из файла .env.

Его пример:

ENV=dev
MYSQL_ROOT_PASSWORD=password
MYSQL_DATABASE=laravel_database
MYSQL_USER=laravel_user
MYSQL_PASSWORD=laravel_password
PROJECT_URL=localhost
PROJECT_ROOT=/var/www/public
DIRTY_HACK=$
VIRTUAL_HOST=localhost
VIRTUAL_PORT=8000

Конфигурация nginx

Так же в docker-compose.yml используются файлы для конфигурации ngnix сервиса.

Создайте в проекте папку nginx и подпапку conf.d с двумя файлами: laravel-conf.template и laravel.conf.

В первом файле мы опишем базовую структуру конфигурации ngnix и использованием переменных из .env, после чего во время создания контейнера сервис создаст файл с итоговой конфигурацией и будет его использовать для своей работы.

Пример laravel-conf.template:

server {
    listen       ${VIRTUAL_PORT};

    client_max_body_size 100M;

    server_name  ${PROJECT_URL};

    access_log /var/log/nginx/${PROJECT_URL}-access.log;
    error_log /var/log/nginx/${PROJECT_URL}-error.log;

    root ${PROJECT_ROOT};

    index index.php index.html index.htm;

    location ~* ^.+\.(jpg|jpeg|gif|png|ico|css|pdf|ppt|txt|bmp|rtf|js)$ {
        #access_log off;
        #expirs 3d;
        #add_header Cache-Control "public, max-age=259200";
        add_header Cache-Control "s-maxage:259200";
    }

    location / {
        try_files ${DIRTY_HACK}uri ${DIRTY_HACK}uri/ /index.php${DIRTY_HACK}is_args${DIRTY_HACK}args;
    }

   location ~ \.php$ {
         fastcgi_param HTTPS on;
                   fastcgi_param DEVEL_SITE 0;
         try_files ${DIRTY_HACK}uri =404;
         fastcgi_split_path_info ^(.+\.php)(/.+)$;
         fastcgi_pass php:9000;
         fastcgi_index index.php;
         fastcgi_param SCRIPT_FILENAME ${DIRTY_HACK}document_root${DIRTY_HACK}fastcgi_script_name;
         include fastcgi_params;
   }
}

Заключение

Таким образом мы подготовили все необходимое для создания образов и контейнеров.

Выполните команду:

docker-compose up -d

Docker посредством содержимого docker-compose.yml создаст контейнеры из указанных в файле образов, после чего автоматически их запустит.

Флаг -d преобразует процесс в демона, с которым контейнеры остаются запущенными в фоновом режиме.

Для остановки контейнеров возможно использование команды:

 docker-compose down -v

Введение

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

Сотрудникам пришлось осваивать технологии и подстраиваться под работу из дома, где, зачастую нет хорошего освещения (для качественного видео стриминга), красивого одноцветного фона, дети и родственники регулярно появляющиеся в кадре и отвлекающие внимание. Появилась функциональность виртуального фона (также известная как замена или размытие фона в видеозвонках, или перерождение хромакея в умный хромакей, который не требует однотонного фона), это когда автоматически в режиме реального времени в видео заменяется фон на заранее выбранную картинку или размывается чтобы не было видно что происходит за человеком. Одни из первых такую функциональность ввели компании Zoom, Skype, Google.

Популярность росла, пользователи уже не просто интересовались, а требовали наличия виртуального фона во всех программах связанных с видеозвонкам. Собственная разработка - долго  и дорого, а также требует определенных компетенций команды, а готовых решений на рынке просто не было. В этой статье мы расскажем про путь создания собственного кроссплатформенного решения позволяющего заменять/вырезать фон в видео с веб камер в режиме реального времени.

Существующие подходы

Традиционно для удаления фона применяли технику «зеленого экрана», когда пользователь ставит позади себя однотонное полотно, цвет которого считается фоновым. В таком случае достаточно вырезать пиксели, соответствующие основному цвету, и некоторый объем вокруг этой точки, чтобы исключить «протекание» фона из-за неравномерности освещения экрана или шумов камеры. Такое решение позволяет получить хорошую картинку, но требует от пользователя определенных усилий для подготовки места съемки. Это не будет большой проблемой для людей, регулярно ведущих трансляции, но для повседневного или рабочего общения в чатах хотелось бы обойтись вообще без подготовки.

При удалении фона нам необходимо классифицировать каждый пиксель как “человек” или “фон”, что полностью совпадает с постановкой задачи сегментации изображения. И тут на сцену выходят свёрточные нейронные сети. С момента их дебюта на соревновании по классификации изображений ImageNet Large Scale Visual Recognition Challenge прошло много времени и им покорились многие задачи компьютерного зрения. Именно методы на основе нейронных сетей уверенно держат верхние позиции во всех бенчмарках по сегментации изображений, что делает их очевидным кандидатом для решения задачи определения фона.

Перед нами стояло две основных задачи. Во-первых, подготовить набор данных для решения именно нашей проблемы. Во-вторых, разработать архитектуру, пригодную для запуска на достаточно слабом железе, включая ограниченные по мощности процессоры ноутбуков и мобильные устройства на Android и iOS.

Существующие наборы данных

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

MS COCO

Стандартный датасет, использующийся как бенчмарк в работах по детекции и семантической сегментации изображений. Они содержит достаточно большое количество примеров с людьми, но эти изображения далеки от тех, что обычно встречаются при использовании веб-камер. Качество масок тоже оставляет желать лучшего, особенно на границах контура человека.

Supervisely Person

Набор данных, созданный специально для определения людей на изображениях. Источником изображений послужили фотографии с фотостоков. Хотя визуальное качество масок в этом датасете достаточно высокое, исходные изображения слишком далеки от того, что обычно можно увидеть на кадрах с веб-камер: фон размыт и фокус сделан на человеке, сцена хорошо освещена, разрешение снимка высокое, шума практически нет. Обученные на таком датасете модели не подходят для решения нашей задачи.

AISegment.com - Matting Human Datasets

Датасет для решения очень похожей на нашу проблемы - portrait matting. Основных отличий от нашей постановки два. Во-первых, вместо жесткой классификации тут требуется определить значение прозрачности в диапазоне [0; 1], что позволяет более качественно разделять фон и человека в сложных ситуациях. Например, четко определить границы волос довольно трудно и использование мягкого несколько улучшает визуальные характеристики результата. Во-вторых, авторы датасета ограничились портретными фотографиями с характерным ограничением разнообразия поз в них. В частности, обученные на этом датасете модели не могут корректно определять руки.

Сбор собственного набора данных

После изучения датасетов и нескольких безуспешных попыток обучить на них модель с приемлемым качеством мы решили, что лучшим способом добиться результата будет обучить модель на картинках напрямую из целевого домена. Хотелось получить датасет напрямую с веб-камер, чтобы визуальные характеристики изображений, которые модель увидит во время обучения, совпадали с кадрами, на которых будет производиться вывод. Первыми “жертвами” стали сотрудники нашей компании, которых мы попросили на добровольной основе записать для нас небольшие ролики с демонстрацией различных положений.

Количества и разнообразия собственных данных не хватило для того, чтобы значительно улучшить результаты модели. Погрустив над тем, что расширить датасет путем сбора данных с реальных людей не представляется экономически возможным, мы решили обратиться к самой большой коллекции видео на Земле – YouTube.

Мы собрали около 300 роликов из видео-блогов и записей стримов, достаточно похожих по качеству съемки на целевой домен. При сборе мы старались больше внимания уделять роликам, снятым в плохих условиях на плохие камеры, и следили, чтобы профессионально настроенные сетапы были в меньшинстве. Сбор данных и их разметка шла итеративно по мере улучшения модели, и каждый новый раунд разметки улучшал результат даже без изменения модели. На данный момент датасет состоит из примерно 12000 картинок с качественными масками.

Кроме самого набора данных, важную роль в улучшении результатов сыграл подбор существующих и разработка собственных аугментаций. Для построения пайплайна мы использовали библиотеку Albumentations. В ней реализован большой набор аугментаций и предлагаются абстракции для построения цепочек аугментаций (с возможностью ветвления), каждая из которых активируется с определенной вероятностью. Были использованы цветовые (смещение цветов в RGB, гауссов аддитивный и мультипликативный шумы, перестановка каналов, симуляция шума сенсора камеры, изменения яркости и насыщенности, блюр и т.д.) и пространственные (поворот, отражение) преобразования. Мы самостоятельно реализовали аугментации для замены фона и наложения синусоидального шума. Последний помогал при наличии мерцания на изображении из-за особенностей поведения сенсора камеры при включенном искусственном освещении.

Аугментации не отразились существенно на метриках, зато значительным образом улучшили стабильность поведения модели «в естественной среде».

Модель

Хотя данные в нашем случае были ключом к получению качественной сегментации, модель все еще играет важную роль. Особенно когда важна максимальная производительность и просто взять готовую сеть целиком из статьи нельзя. В основу архитектуры мы положили схему“encoder-decoder”. Первая часть сети (encoder) поэтапно извлекает признаки из исходного изображения, снижая пространственное разрешение карты признаков в 2 раза на каждом этапе обработки. Итоговое разрешение карты признаков может быть в 32 раза меньше исходного и предсказать достаточно мелкие детали на таком маленьком разрешении затруднительно. Поэтому вторая часть сети использует признаки из исходного изображения и поэтапно восстанавливает разрешение до исходного.

Первая версия архитектуры представляла из себя энкодер-декодер с использованием миниатюрной DenseNet в качестве энкодера и последовательности слоёв билинейной интерполяции. Хотя производительность сети нас устраивала, модель могла предсказывать только общий контур сидящей смирно фигуры. Сложный фон или поднятые руки сбивали модель с толку.

Эксперименты с сетью UNet показали высокую точность, однако скорость вывода даже на GPU была слишком низкой. Мы попробовали разные варианты наивного масштабирования: уменьшение разрешения входа, уменьшение глубины карт признаков, удаление стадий декодирования, но качество падало быстрее, чем увеличивалась скорость модели. В итоге мы заменили обычные свертки на depthwise-separable варианты. Это увеличило скорость до приемлемых показателей без существенной потери в качестве. Такая модель первой преодолела рубеж качества, достаточного для деплоя и демонстрации.

Параллельно мы оценивали легковесные модели на основе “dilated”свертки, однако получить быстрые модели с достаточно высоким качеством в короткие сроки не получалось, и мы забросили это направление исследований полностью.

Вдохновением для последующих версий модели послужила работа по оценке глубины с помощью UNet-подобной сети, в которой авторы предложили ассиметричную архитектуру с легким энкодером и тяжелым декодером. Еще одной важной идеей было получение предсказания в меньшем разрешении по сравнению с входной картинкой. Мы взяли эти две идеи и реализовали свою собственную модель, использовав легковесные боттлнеки и несколько упростив декодер. От расчета ошибки на нескольких разных масштабах отказались, так как не наблюдали его влияния на качество. Вместо него мы добавили в сеть дополнительную ветку, которая использовала последнюю карту признаков для расчета ошибки только на границах маски. Она позволила немного улучшить стабильность предсказания на границах.

Деплой модели

После обучения модели её необходимо подготовить к разворачиванию в продакшене. На первых этапах предполагалось развертывать модель в составе нативных приложений на платформе Windows с возможность запуска нейронки на CPU и на GPU. К сожалению, деплоить модель напрямую с помощью PyTorch не представляется возможным из-за маленькой скорости инференса на CPU. Кроме того, поддержка GPU Windows ограничена карточками nvidia, бинарь библиотеки весит около 3 Гб и на стороне пользователя требуется установка CuDNN, так как её нельзя распространять в составе собственных решений.

Приняв этот печальный факт, мы обратились к другим решениям, нацеленных только на эффективный инференс сетей. Благо, что накопилось достаточное количество зрелых альтернатив.

WinML

В первую очередь наш взгляд упал на WinML – библиотека для вывода нейронок от Microsoft, интегрированная в Windows 10 начиная с версии 2004. Оно позволяет запускать модели на CPU и GPU, причем любых вендоров. Библиотека понимает только сериализованные в ONNX модельки. Благо, что в PyTorch конвертация модели делается в пару строчек.

С помощью WinML мы смогли быстро получить первые рабочие прототипы и продолжить исследование доступных средств для запуска нейронных сетей.

OpenVINO

Фреймворк от Intel для оптимизации и вывода нейронок на процессорах x86 и интегрированных в процессоры GPU. OpenVINO реализует большое количество операторов, особенно необходимых для компьютерного зрения, так что напороться на несовместимость шансы не так велики. Все это великолепие сопровождается отличной документацией, тулами для тестирования и бенчмаркинга моделей, большим зоопарком уже готовых для использования моделей. Напрямую из PyTorch модель экспортировать нельзя, сначала нужно сконвертировать её в ONNX, Разумеется, поддерживается интеграция в C++ проекты.

После демонстрации десктопного SDK мы получили запрос на добавление возможности запуска модели на мобильных устройствах и в веб-браузерах.

MediaPipe

Для начала мы попробовали библиотеку MediaPipe, созданную в недрах Google. Основные сценарий её использования это реализация пайплайнов потоковой обработки видео и аудио в мультимедийных приложениях. Вы описываете источники данных (камера, микрофон), последовательность манипуляций над данными в виде графа, а фреймворк берет на себя заботы по обслуживанию процесса обработки. За вывод нейронок отвечает TensorFlow Lite. Библиотека поддерживает десктопные и мобильные платформы, но с оговорками, о которых мы поговорим ниже.

Так как этот фреймворк не поддерживает импорт из ONNX и PyTorch, сначала нужно решить вопрос перегонки модели в понятный ему формат. После изучения опыта хождения по граблям других людей, мы пошли по не самому простому пути, но с наиболее предсказуемым результатом – повторной реализации модели на TensorFlow и импорта весов из PyTorch. Процесс этот несложный и достаточно механический. Требуется только помнить о том, что TF по умолчанию использует NHWC формат тензоров, а PyTorch – NCHW. Эта несовместимость лечится простым транспонированием весов сверточных слоёв при импорте. Портировав таким образом модель на TensorFlow и убедившись в правильности процесса путем сравнения ответов сети, мы преобразовали сеть в формат TensorFlow Lite и принялись за запуск MediaPipe на мобильных девайсах.

На Android нам пришлось самостоятельно реализовать несколько операций (вроде склейки предыдущей маски с текущим изображением) для обработки изображений на OpenGL, но в целом запуск модели прошел гладко и занял около двух дней. На не самых продвинутых устройствах мы смогли получить уверенные 25-30 FPS, что нас несомненно обрадовало. К тому же, к тому времени у нас были пути дальнейшей оптимизации модели.

К сожалению, с iOS все пошло не так гладко. Главной проблемой стала политика Apple, из-за которой мобильные устройства так и не получили поддержку вычислительных шейдеров OpenGL и пришлось экспериментировать с конвертацией текстур из OpenGL в Metal и обратно. Быстро реализовать это не получилось, поэтому мы отказались от использования MediaPipe на iOS.

CoreML

CoreML является родным для экосистемы Apple фреймворком для запуска нейронных сетей. Он поддерживает все железки этой компании, включая встроенные в SoC NPU (Neural Processing Unit). Процесс портирования оказался гладким, так как Apple позаботилась о путях прямой конвертации модели из PyTorch в CoreML. В итоге портированная модель показала около 30 FPS.

Web

Многие приложения сейчас с самого начала делаются как веб-ориентированные (тем более есть замечательный WebRTC), поэтому упускать возможность предложить им нашу модель не хочется.  Мы попробовали три опции: ONNX.js, TensorFlow.js и TensorFlow Lite. Опыт, к сожалению, был довольно болезненный и удовлетворительно на данный момент работает только одно решение.

Самый простой путь к запуску модели, в теории, представляет ONNX.js, который позволяет подгружать ONNX-модели и исполнять их на GPU или CPU. Картину портит только то, что библиотека не так активно поддерживается и поддерживает импорт ограниченного набора операторов и только из старых версий ONNX IR. Из-за этого могут быть проблемы при экспорте моделей из новых версий PyTorch. Например, в нашем случае проблемой стали слои транспонированной свертки и апсемплинга. Быстро побороть их не получилось мы пошли исследовать другие варианты.

TensorFlow.js представляет собой полноценный фреймворк для обучения и запуска нейронных сетей в JavaScript. В частности, можно импортировать графы из обычного Tensorflow. Мы взяли модель, подготовленную для мобильной версии, и без проблем смогли запустить модель на GPU через WebGL. Проблемы возникли с выводом на CPU при использовании XNNPACK – операция транспонированной свертки давала неверные результаты.

Последним исследованным вариантом был TensorFlow Lite, скомпилированный в WebAssembly с помощью emscripten. WebAssembly – это стандарт, определяющий независимый от платформы байткод, который может исполняться в песочнице. Он был создан в первую очередь для ускорения программ, которым недостаточно производительности JavaScript в браузерном окружении. Тулчейн emscripten позволяет компилировать программы на C/C++ в WebAssembly. К нашему счастью, TensorFlow Lite как раз написан на C++, что позволяет запустить его напрямую в браузере. Скомпилированная версия TensorFlow Lite быстро завелась и показала достаточную для деплоя производительность. Кроме того, такой способ деплоя открывает возможность использовать другие библиотеки, например, OpenCV для пре- и постпроцессинга изображений, чем мы с радостью воспользовались.

Главным препятствием на пути интеграции стало отсутствие встроенных средств шифрования моделей во всех рассмотренных нами фреймворках. Именно по этой причине мы остановились на варианте с компиляцией TensorFlow Lite, так как он позволяет реализовать шифрование модели самостоятельно.

Что получилось

Сейчас у нас подготовлены четыре версии SDK для всех основных платформ с быстрой, стабильной и качественной сегментацией фона. Есть интеграции с коммерческими проектами. Мы продолжаем развивать это направление. Вот сайт продукта: https://tomsksoft.com/solutions/cross-platform-virtual-backgroung-sdk

А вот пример работы самой сегментации на десктопе:

Данный курс представляет собой введение в язык программирования Python и среду разработки Jupyter Notebook и ориентирован на студентов физико-математических специальностей. Мы постарались сделать курс максимально простым и не требующим предварительной подготовки в области программирования, поэтому особое внимание уделяем объяснению основополагающих понятий: компиляция/интерпретация, типы данных, переменные, ссылки, объектно-ориентированное программирование (ООП) и т.д. Заключительная глава посвящена краткому рассмотрению основных библиотек языка Python для решения задач технических вычислений: NumPy, Mathplotlib и Pandas.

Курс был разработан для студентов Томского центра университета Heriott-Watt, занимающихся таким популярным в наши дни направлением, как Machine Learning. Университет Heriott-Watt специализируется на подготовке специалистов нефтегазового дела и занимается развитием методов использования алгоритмов Machine Learning для анализа месторождений.

Пройти курс онлайн можно, перейдя по этой ссылке. Скачать курс можно здесь.

Инструмент для автоматизации развертывания веб-приложений

Речь пойдет про простой инструмент для развертывания (деплоя) сайтов и сервисов на Linux системы. Сделали сами, пользуемся несколько лет, при определенных обстоятельствах может пригодится и вам, пользуйтесь.

Состоит из пары bash скриптов (интегрируются в исходный код проекта), а для их работы нужны только стандартные утилиты Linux (наличие git на целевых серверах не требуется).

Обеспечивает:
- развертывание вашего проекта на любое количество серверов
- проверка корректности среды для развертывания
- детектирование локальных изменений файлов
- возможность полностью автоматически последовательно вернуться на три предыдущие версии
- очистку сервера от старых, неиспользуемых версий
- легкую интеграцию в проект
- совместимость с любой системой CI, которая поддерживает запуск bash скриптов

Подходит для:
- веб сайтов, работающих под управлением ngnix, apache, и вообще, любого веб-сервера, у которого понятие «сайт» - это каталог где расположен корень сайта (doc_root)
- сервисов, представляющих собой запускаемый модуль (бинарный или скриптовый)
- проекта, которые развертывается на целевую систему в виде конкретного каталога или файла (при этом он может иметь взаимосвязи с другими каталогами системы без ограничений) и у проекта есть «точка входа» которая полностью идентифицируется этим каталогом или файлом

На картинке это можно представить вот так:

Вы интегрируете в код проекта пару скриптов, настраиваете на своей системе CI их запуск в том workflow которое у вас принято, после чего CI занимается тем, что копирует по scp установочные пакеты и скрипт для развертывания на удаленные сервера, и запускает его там, а скрипт выполняет всю работу, при этом обеспечивает диагностический вывод, возврат статуса завершения, перед деплоем выполняет диагностику окружения для уменьшения вероятности сбоев.

Зачем это надо, если есть Docker и git и другие инструменты?

Главная фишка тут – почти полная независимость от внешней среды. Из внешних зависимостей тут только Linux, bash и их стандартные утилиты и команды. А они как известно поддерживают крайне стабильную совместимость между системами и поколениями. Это может сыграть ключевую роль там, где необходимо поставлять проект на самые разные системы/сервера, когда у вас нет возможности обеспечить на них совместимую среду для более сложных пакетов (даже python скрипты не будут работать где угодно!), и там, где нет ресурсов (сил, желания) тянуть проект на постоянно развивающихся (и не всегда заботящихся об обратной совместимости) системах CI и DevOps.

Второе, но не менее важное – это отсутствие backdoor для доступа к вашему репозитарию извне, т.к. система не использует git на серверах, куда деплоит проект.

Ну и третье, если Вам просто невозможно использовать что-то другое (заказчик запретил, система не поддерживает, и другие, экзотические случаи).

Мы сами являемся сторонниками перехода на доставку с помощью Docker-а и сейчас переводим наши основные проекты на него, но вот старые, те что живут на одной поддержке и не планируются к развитию, оставляем на этом инструменте, который был разработан и внедрен пару лет назад, и успешно эксплуатируется все это время в связке со всеми перечисленными в статье инструментами и технологиями.

Этапы внедрения автоматического деплоя сайтов и сервисов

Для того, чтобы это полностью заработало, нужно сделать следующие шаги:

1. Включить скрипты сборки установочного пакета и деплоя в репозитарий вашего проекта (0.5-10 минут)
2. Настроить эти скрипты для работы с инфраструктурой проекта (для первого раза 30-60 минут, со второго минут 10-15)
3. Подготовить на серверах для деплоя структуру каталогов для работы скрипта (для первого раза с полчаса, дальше не более нескольких минут).
   
   И с этого момента оно уже работает, но для полноценной интеграции в CI конечно еще нужно:
   
4. Если проект имеет сложную инфраструктуру (внешние зависимости, создает временные файлы внутри себя, и т.д. и т.п.), потребуется чуть более тонкая настройка – делаем ее и отлаживаем скрипты до полной работоспособности
5. Включить запуск скриптов сборки и деплоя в вашу CI в соответствии с вашим workflow (это может быть любая система, которая поддерживает запуск bash скриптов, например, Gitlab CI или Jenkins)
6. И написать краткую инструкцию для разработчиков как этим пользоваться (полчаса, шаблон типовой инструкции приведен в конце статьи)

Пошаговая инструкция по автоматизации развертывания веб-приложений в проекте

Шаг 1, добавляем в проект скрипты для подготовки установочного пакета и деплоя:

Создаем в корне своего проекта каталог CI, скачиваем в него два скрипта: deploy.sh и build-inst.sh вот отсюда https://github.com/tomsksoft-llc/ci-deploy-scripts-bash.git

Не нравится имя каталога CI? Используйте любое другое, только учитывайте это при дальнейшей настройке.

Шаг 2, настраиваем скрипты под наш проект:

build-inst.sh – скрипт создания установочного пакета, запускается только на билд-сервере, на удаленных серверах не нужен.

В самом верху скрипта строчка:

INSTALL_PCKG_SUFFIX="my_project"

Меняем «my_project» на что подходит для вашего проекта. Это будет использовано как часть имени файла установочного пакета.

Дальше ищем:

tar -czf "${BUILD_VERSION}_${INSTALL_PCKG_SUFFIX}.tgz" --exclude="CI" ./* 

Создание пакета – это просто архивирование всех нужных файлов в один файл, при этом исключаются не нужные, в данном случае каталог с нашими скриптами. Что бы исключить еще что-то, просто пишем следующий –exclude=”bla…..” и так сколько надо. Внимание! Некоторые версии tar имеют чуть другой синтаксис, проверьте что на вашем билд-сервере оно работает как вам надо. Этот скрипт будет запускаться только там и нигде более.
Можете переписать скрипт как угодно вам, интегрировать его в ваш процесс сборки, или просто взять из него одну строчку для получения архива – как вам удобнее.
Задача – получить файл архива, который можно перенести на удаленный сервер, развернуть и запустить из полученных файлов ваш проект.

deploy.sh – он выполняет все функции, перечисленные в начале статьи, работает на удаленных серверах.

Верхняя часть файла, константы, задаем их:

OWNER="myusername"

Здесь надо указать имя того пользователя, под которым ваш CI будет заходить на удаленные сервера по ssh.

TARGET_DIR_STATE="drwxr-xr-x${OWNER}mygroupname"

Вместо mygroupname укажите имя группы, которой принадлежит каталог в который мы будем выполнять деплой.
В начале строки указаны права на этот каталог, их можно поменять, главное, чтобы они соответствовали действительности, скрипт будет это проверять при деплое и вываливаться с ошибкой если найдет отличия.

BUILDS_DIR_STATE="drwxr-xr-x${OWNER}mygroupname"

Все тоже самое, но для каталога, который находится уже внутри предыдущего. В этом каталоге хранятся версии вашего проекта. Обычно все должно совпадать с предыдущим каталогом, но мало ли…. Кстати, он называется revs. Если хотите поменять это имя – меняйте, в предыдущей строке:

BUILDS_DIR="revs"

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

SITE_ROOT_SYMLINK="site" 
SITE_ROOT_SYMLINK_STATE="lrwxrwxrwx${OWNER}mygroupname"

Это название и права доступа к файлу сим-линку, который будет указывать на текущую рабочую версию. Именно имя этого сим-линка вы должны использовать в качестве «doc_root» при настройке веб сервера. Здесь также задайте имя группы, которой будет принадлежать файл, и если нужно поменяйте его имя и права доступа.

Шаг 3, подготовка структуры каталогов на сервере:

На сервере(ах) куда будем деплоить нужен локальный пользователь и группа, которые мы задали в конфигурации на предыдущем шаге.
Создаем каталог в который будем все заливать-деплоить, назначаем ему владельцев и права которые задали в конфигурации.
Внутри этого каталога создаем подкаталог revs (или как вы его назвали на предыдущем шаге) и назначаем ему владельцев и права которые указали в конфигурации.
Создаем файл сим-линк (указывающий куда угодно, хоть на несуществующий файл), назначаем ему владельца и права, которые задали в конфигурации.
Если у нас уже развернута живая система на этом сервере, то, есть хитрость легко переехать на данную систему без даунтайма. Но об этом позже, давайте сначала убедимся, что у нас все заработало.

Вот пример как можно это сделать:

$ mkdir myproject
$ chmod 755 myproject/
$ mkdir myproject/revs
$ chmod 755 myproject/revs/
$ ln -s foo myproject/site

Вот что примерно получится:

drwxr-xr-x 3 myuser mygroup 4096 Sep 19 11:51 myproject:
  drwxr-xr-x 2 myuser mygroup  4096 Sep 19 11:51 revs
  lrwxrwxrwx 1 myuser mygroup 3 Sep 19 11:51 site -> foo

Шаг 4, приступаем к использованию, тонкая настройка

Давайте попробуем получить установочный пакет, для этого переходим в корень репозитария нашего проекта и запускаем:

$ ./CI/build-inst.sh 1
Try to build for 1:
OK: Build successfully.

В результате получим файл 1_myproject.tgz, в текущем каталоге.

Вот так его можно задеплоить на наш удаленный сервер (где мы уже настроили инфраструктуру):

$ scp CI/deploy.sh myuser@myserver:~
$ scp 1_myproject.tgz myuser@myserver:/home/myuser/myproject/revs/
$ ssh myuser@myserver bash ~/deploy.sh /home/myuser/myproject /home/myuser/myproject/revs/1_myproject.tgz

Каталоги надо указывать полностью от корня, т.к. скрипт работает с сим-линками, а нам не надо, чтобы получились относительные сим-линки (тогда уже при запуске самого приложения точно будут проблемы).

Я здесь не останавливаюсь на том, как обеспечить доступ по ssh, но проще всего сделать это с помощью RSA ключей. На билд сервере будет лежать закрытая часть ключа, а на удаленном, открытая в каталоге пользователя, под которым мы идем (тогда для команд scp и ssh надо будет указать ключ: -i с именем файла ключа в качестве первого аргумента команды).
Инструкции как это сделать можно легко найти в интернете.

Если у вас получилось, то скрипт выполнится успешно, и на удаленном сервере вы увидите такое состояние каталогов:

myproject:
lrwxrwxrwx  1 myuser mygroup   23 Sep 19 12:16 backup1 -> /home/myuser/myproject/foo
drwxr-xr-x  3 myuser mygroup 4096 Sep 19 12:16 revs
lrwxrwxrwx  1 myuser mygroup   36 Sep 19 12:16 site -> /home/myuser/myproject/revs/1_myproject

В каталоге /home/myuser/myproject/revs/1_myproject будет развернуто содержимое файла архива, который мы передали в качестве инсталляционного пакета.
При этом сам файл архива после успешного деплоя удаляется.

В процессе выполнения скрипта он выведет кучу диагностики – это нормально. В случае, если что-то пошло не так, скорее всего она вам поможет найти ошибку. Если же все было ОК, то завершающий вывод будет примерно таким:

OK...............: Deploy script deploy.sh
    on myserver
    for /home/myuser/myproject
    from  /home/myuser/myproject/revs/1_myproject
    successfully done.

Теперь надо учесть внешние зависимости нашего проекта. Это могут быть постоянные файлы/каталоги, которые должны сохранятся от деплоя к деплою (простейший пример – конфигурационные файлы и файлы локальных настроек).
Принцип похож на тот, что используется в докере – мы просто храним такие каталоги и файлы локально на удаленном сервере в отдельном месте выше каталога проекта (можно и даже нужно их хранить в каталоге куда мы выполняем деплой, т.е. в нашем случае в /home/myuser/myproject, но это не обязательно, делайте как вам удобнее), а при деплое, линкуем их в нужные места в каталоге где развернута конкретная версия (если таких зависимостей в вашем проекте нет, то переходите сразу к пункту «Правила использования скрипта deploy.sh»).

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

Функция deploy_project_environment() – именно сюда добавляем действия, которые надо выполнить между тем моментом, когда архив уже развернут (т.е. все новые файлы на месте) и тем, когда рабочий сим-линк будет переключен на каталог с новой версией. Если вы вернете из э той функции НЕ ноль, то деплой будет остановлен, и переключения на новую версию не произойдет (старая версия останется работать как ни в чем не бывало).
Например там может быть создание линка внутри только что развернутой версии проекта на файл или каталог который лежит выше и является перманентным (сохраняется между сменами версий). Можно сделать это так:

if ! create_symlink "$_target_dir/.env" "$_build_dir/.env"
then
    return 1
fi

Функция create_symlink объявлена внутри нашего скрипта, можете использовать ее просто для удобства, она работает сразу и с каталогами и с файлами и выводит стандартное диагностическое сообщение.
Этот и еще один пример в закомментированном виде есть в самом скрипте, пользуйтесь. Ну и вообще, делайте что нужно, а в случае ошибки возвращайте НЕ ноль чтобы прервать деплой в тот момент, когда на живой системе еще нет никаких изменений.

Функция test_env_cons() – сюда можно вставить любые проверки, они будут выполнены еще до попытки распаковать файл. Если функция возвращает НЕ ноль, то деплой будет остановлен. В этой функции уже есть три проверки – на существование и правильность прав доступа к основному каталогу, каталогу с ревизиями и сим-линку на рабочую версию. Можете расширять по образу и подобию своими проверками, закомментированный пример есть в коде скрипта. Функция test_dst, которая используется в примерах, определена внутри скрипта, можете пользоваться ей просто для удобства.

Функция test_content() – она ищет файлы, которые были изменены в рабочей версии уже после того, как она стала основной рабочей. Для того, чтобы избежать реакции на файлы или имена каталоги, которые могут меняться исключите их таким образом:

ищем строчку

if [ "$(find "$link_src" -newer "$link" | wc -l)" -gt 0  ]

и для исключения, например, файла .env, добавляем его вот таким образом:

if [ "$(find "$link_src" -newer "$link" | grep -v .env | wc -l)" -gt 0  ]

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

find "$link_src" -newer "$link" | grep -v .env

Правила использования скрипта deploy.sh

Получить справку по использованию можно запустив скрипт без аргументов:

deploy.sh [-f|--force] TARGET_DIR   BUILD      - to deploy BUILD into TARGET_DIR
TARGET_DIR - directory where all environment will be deployed.
BUILD can be .tgz archive or a directory within TARGET_DIR/revs.
force: Deploy anyway (the script will delete existing directory and ignore local changes).

deploy.sh [-t|--test] TARGET_DIR             - to test environment consistent in TARGET_DIR
deploy.sh [-r|--restore] TARGET_DIR          - to restore live from backup1 link if it exist in TARGET_DIR
deploy.sh [-с|--content] TARGET_DIR          - to check if any file(s) was changed after deploy in TARGET_DIR
deploy.sh [-s|--scavenge] TARGET_DIR         - delete old not used revision in TARGET_DIR
deploy.sh [-h|--help]                        - to print this message

Основная функция - это деплой, ее синтаксис указан в самом начале описания. Немножко пояснений по поводу флажка force – по умолчанию скрипт если наткнется на любую проблему сразу же прервет деплой (например, уже существует версия с таким же именем как вы хотите задеплоить, или в текущей активной ревизии есть файлы с локальными изменениями). Если вы укажете ключ -f, то такие проблемы будут проигнорированы, но резервная копия при этом все равно будет создана (путем переименования старого каталога).
Функция очистки -s удаляет только те ревизии, которые не являются бекапной копией или текущей рабочей системой, и при этом каталог создан не менее чем за 5 дней до момента на который производится очистка.
Функция restore возвращает систему на одну версию обратно, т.е. текущая рабочая версия заменяется версией из backup1, backup1 заменяется версией из backup2 и т.д. Всего хранится три бекапных линка, но если надо больше, то просто поменяйте код скрипта в функции link_to_site() (увеличьте счетчик цикла, который создает бекапные линки до нужного вам значения).

Отлаживаем и запускаем

Остается теперь перенастроить ваш сервер так, чтобы он брал ваш сайт по нашему сим-линку site. Например, для веб серверов достаточно просто указать его в качестве doc_root. Бывают специфические настройки, которые влияют на поведение веб серверов при таком деплое, например, для ngnix желательно использовать директиву $realpath_root.

Проще и надежнее всего поднимать новую систему рядом с уже существующей, с другим именем хоста, там все отлаживать и проверять, и уже потом менять имя хоста в конфигурационном файле веб-сервера.
И только если вам позволяет опыт, цена ошибки не высока и вообще, все звезды сложились, то можно попробовать сделать так: укажите текущему сим-линку целевой каталог где на данный момент находится ваша система, перенастройте сервер и выполните рестарт. Дальше разберитесь с внешними зависимостями, например, все что нужно оставьте в каталоге вашей текущей системы (ведь она сейчас работает), настройте скрип деплоя чтобы линки делались туда, и пробуйте деплой. Если с первого раза не получилось, просто выполняйте restore, он будет возвращать сим-линк на ваш прежний каталог.

Шаг 5, как это интегрировать в инфраструктуру проекта и его workflow:

Для интеграции деплоя в ваш CI, нужно просто вставить запуск наших скриптов в нужные места. Тут все зависит от вашего workflow и инфраструктуры. Например, для формирования инсталляционного пакета используете команду:

./CI/build-inst.sh <$Version_id>

Где в качестве Version_id можете использовать номер сборки, хеш ревизии из git, или их комбинацию. Это позволит кроме всего прочего легко идентифицировать какая ревизия залита на вашу систему (конкретный сервер).
Не забывайте в CI обрабатывать код возврата. Скрипты в случае ошибки возвращают НЕ ноль, реагируйте на это (хотя, например, Jenkins и Gitlab CI отреагируют на это сами и прервут выполнение своей Job-ы).

Для деплоя используйте комбинацию команд:

$ scp -i id_rsa_file_name CI/deploy.sh myuser@myserver:~
$ scp -i id_rsa_file_name <install_pkg_name>.tgz myuser@myserver:/home/myuser/revs/
$ ssh -i id_rsa_file_name myuser@myserver bash ~/deploy.sh /home/myuser/myproject /home/myuser/myproject/revs/<install_pkg_name>.tgz

Если серверов несколько, то сначала копируйте инсталляционный пакет на все, и если все получилось, только тогда на каждом из них, последовательно, запускайте скрипт деплоя.
Если на одном сервере несколько проектов, то просто переименуйте скрипт deploy.sh прямо в репозитарии проекта (добавьте к имени файла идентификатор проекта) и тогда вы избежите перетирания файлов при деплое разных проектов на один сервер.
Если после деплоя нужны дополнительные действия для вступления изменений в силу – вставляйте эти команды сразу после скрипта деплоя (не забывая обрабатывать его код возврата!). Это могут быть, например, рестарт php-fpm, рестарт вашего сервиса и т.д. и т.п.

Кроме этого, можно еще по крону раз в день запускать на билд-сервере скрипт примерно такого содержания:

$ ssh -i id_rsa_file_name myuser@myserver "/bin/bash ~/deploy.sh -t /home/myuser/myproject"
$ ssh -i id_rsa_file_name myuser@myserver "/bin/bash ~/deploy.sh -c /home/myuser/myproject"
$ ssh -i id_rsa_file_name myuser@myserver "/bin/bash ~/deploy.sh -s /home/myuser/myproject"

Выводить это в лог и отслеживая код завершения каждой из команд, например, в случае ошибки присылать на почту.
Такой подход позволит вам обнаружить ошибки в инфраструктуре сразу в день их появления (иначе, можно обнаружить ее через полгода, когда срочно надо залить какое-то изменение в проект, а тут выясняется, что у вашего пользователя больше нет доступа к серверу…).
Хотя это на ваше усмотрение, мы такой подход используем и он себя оправдывает (например, смена IP адреса на билд-сервере, в результате чего тот теряет доступ к серверам, ну потом что там настроен firewall, и не пускает кого попало – вы об этом узнаете в тот же день и исправляете по горячим следам).

Шаг 6, пишем инструкцию по использованию для разработчиков на основании шаблона:

Просто приведу пример такой инструкции, основано на одном из наши workflow для конкретной группы проектов. Если будете делать такую инструкцию для ваших инженеров по данному шаблону, это займет несколько минут 30 (вместе с перерывом на чай/кофе):

Если решите использовать данные скрипты, помните – мы не несем ответственности за последствия их применения в первозданном или измененном виде.

Если решились использовать – удачи вам, и пожалуйста, поделитесь с нами своим успешным опытом!

CIS - это инструмент для разработчиков программного обеспечения.

CIS является системой непрерывной интеграции и предназначен для  автоматизации рутинных операций, которые присутствуют в жизненном цикле  ПО таких как: сборка, развертывание, автотестирование, диагностика  состояния систем и т.д.

В отличии от других систем непрерывной интеграции ядро CIS можно  запускать локально без остальных компонентов, что может быть удобно для  отладки разрабатываемых скриптов автоматизации. Все логи, настройки проектов  и переменных доступны в виде обычных  текстовых файлов, что позволяет хранить конфигурацию CI в системах  контроля версий, а так же переносить проекты вместе со всей историей при  помощи обычного копирования. Веб интерфейс позволяет создавать задачи, изменять их, следить за их  исполнением в реальном времени, просматривать логи и скачивать  полученные артефакты. Так как CIS использует исполняемые файлы в качестве скриптов, то  возможные сценарии использования ограничены лишь возможностями ОС,  правами пользователя и фантазией разработчика. Например пользователь  может использовать docker или другие средства контейнеризации для  сборки. Механизм задач, в свою очередь, позволяет реализовать набор  базовых компонентов для переиспользования подобных приемов.

Скриншоты работы системы:

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

Описание системы

Разрабатываемая система состоит из трех основных частей:

• FrontEnd
• WebUI
• Core

Схема их взаимодействия представлена ниже.

┌────────┐ <─[exec]─ ┌───────┐          ┌──────────┐
│        │ <─[env]── │       │ <[HTTP]> │          │
│  Core  │           │ WebUI │          │ FrontEnd │
│        │ ─[TCP]──> │       │ <─[WS]─> │          │
└────────┘ <[files]> └───────┘          └──────────┘

Ядро является независимой от остальной системы частью системы и может  работать отдельно. В данный момент для корректной работы необходимо устанавливать все  компоненты на один сервер или в один контейнер. При этом существует  возможность разработки небольшой прослойки, которая позволит запускать  ядро и webui на отдельных серверах.

Core

Ядро является ключевым компонентом системы и содержит в себе логику  запуска задач, работы со сборками, логами и планировщиком. Ядро не  зависит от остальных компонентов и может работать отдельно, как из  терминала, так и из других систем, например задачи ядра могут  запускаться напрямую из GitLab CI Runner'а.

Задачи

Базовой единицей в CIS является задача. Каждая задача представлена  отдельной директорией, содержащей конфигурацию и исполняемый файл  (которой не обязательно является скриптом). У каждой задачи присутствуют  параметры, которые считываются интерактивно, или, могут быть заданы с  помощью аргументов. В рамках сессии параметры задачи могут быть  установлены и считаны с помощью утилит setparam и getparam.

Сессии

При старте первой задачи создается новая сессия, в рамках сессии все  задачи выполняются синхронно, образуя дерево задач. При этом существует  возможность в задаче создать новую сессию. Такую сессию можно выполнять  как синхронно, так и асинхронно, но в асинхронном варианте все задачи  синхронизации ложатся на пользователя. Вся информация о событиях в  сессии логируется в соответствующий файл, и, если webui доступен, то  также отправляется в него посредством TCP. Служебная информация, такая  как пользователь, внутренний адрес webui сервера, имя самой задачи,  номер сборки и другие параметры передаются посредством переменных среды.  Так же существует механизм пользовательских глобальных переменных,  которые видны в рамках одной сессии и могут быть установлены с помощью setvalue и получены с помощью getvalue.

Пример выполнения задач в сессии. Сессия начинается в (а) и завершается в (б):

───────────────────────────────────────────────
 WebUI или терминал
───────────────────────────────────────────────
 ↓ (а)                                ↑ (б)
 ┌────────────────────────────────────┐
 | startjob                           |
 └────────────────────────────────────┘
 ↓                                    ↑
 ┌────────────────────────────────────┐
 | job                                |
 └────────────────────────────────────┘
 ↓          ↑  ↓                      ↑
 ┌──────────┐  ┌──────────────────────┐
 | startjob |  | startjob             |
 └──────────┘  └──────────────────────┘
 ↓          ↑  ↓                      ↑
 ┌──────────┐  ┌──────────────────────┐
 | job      |  | job                  |
 └──────────┘  └──────────────────────┘
                     ↓            ↑
                     ┌────────────┐
                     | startjob   |
                     └────────────┘
                     ↓            ↑
                     ┌────────────┐
                     | job        |
                     └────────────┘

Логи

Ядро ведет несколько логов:

• cis.log - служебные события CIS, в основном ошибки.
• ${session_id}.${n}.log - события в рамках сессии.
• output.txt в директории каждой сборки - вывод самого скрипта сборки.
• ${session_id}.combined.log - полный лог всех событий сессии, информация идентична той, что отправляется в WebUI посредством TCP.

Прочее

В задачи ядра входит очистка директории задачи после сборки, если это  необходимо, так же очистку задачи можно провести вручную при помощи  утилиты maintenance.

Помимо этого ядро позволяет запускать задачи по расписанию аналогично утилите cron.

Существует репозиторий с вспомогательными скриптами используемых для упрощения написания задач - ci-py-lib.

WebUI

Предоставляет API для удаленного управления ядром, просмотра процесса  исполнения задач. Также добавляет функционал управления пользователями,  правами, аутентификации и авторизации. Основной функционал реализован  посредством собственного протокола поверх WebSocket. Дополнительно часть  функций, а именно загрузка и скачивание файлов и вебхуки используют  HTTP. Помимо управления ядром так же реализовано управление файловой  системой, т.к. именно на неё завязано много функций в ядре.

FrontEnd

Реализует интерфейс для API WebUI. Даёт возможность создавать пользовательские сценарии.

Техническая реализация

Зависимости

core

• boost 1.69
• sqlite_orm 1.3
• croncpp 1.0
• sc_logger 1.0.3

webui

• boost 1.69
• rapidjson 1.1.0
• sqlite_orm 1.3
• croncpp 1.0
• sc_logger 1.0.3

Протокол WebUI API

Для взаимодействия с фронтендом или другими внешними системами, а так  же для получения логов из ядра был реализован протокол похожий на  JSON-RPC или WAMP.

Каждое сообщение содержит поле event являющееся уникальным идентификатором события.

Каждое сообщение содержит поле transactionId -  идентификатор транзакции, все ответы сервера на какой-либо запрос  устанавливают значение данного поля равное установленному в запросе.  Позволяет асинхронно взаимодействовать с API по модели RequestReply.

Сообщение может содержать поле errorMessage - отправляется только сервером и содержит дополнительное текстовое описание ошибки.

Поле data содержит произвольные данные специфичные для каждого отдельного события.

Сериализация и десериализация

Для реализации протоколов были реализованы вспомогательные  библиотеки, позволяющие сереализовать и десериализовать JSON на основе  добавления метаописания к C++-типам.

Пример типа с метаописанием:

struct auth_logout
{
    std::string token;
    static constexpr auto get_converter()
    {
        using namespace reflect;
        return make_meta_converter<auth_logout>()
            .set_name(
                CT_STRING("auth"),
                CT_STRING("logout"))
            .add_field(
                CT_STRING("token"), 
                ptr_v<&auth_logout::token>{}) 
            .done();
    }
};

И соотвествующего ему JSON объекта:

{
    "event": "auth.logout",
    "data": {
        "token": string
    }
}

При этом при десериализации происходит автоматическая валидация типа,  так же присуствует возможность задать дополнительные функции валидаторы  для каждого типа.

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

Транспортный протокол между WebUI и Core

Для передачи информации о активной сессии в реально времени был реализован простой бинарный ltv-протокол поверх TCP. В нём присутствует всего 3 типа сообщений - ping, pong и regular.

Первые два используются для проверки того, что соединение активно (в  случае если вторая сторона не отвечает на ping соединение просто  обрывается). Сообщение типа regular может иметь произвольное содержимое.

Данный протокол реализован отдельный библиотекой, с использованием Boost.Asio.

Core

Ядро состоит из нескольких исполняемых файлов, каждый из которых  выполняет отдельную задачу. Для запуска исполняемых файлов используется  библиотека Boost.Process.

Если задача является корневой для сессии, то она считывает параметры  интерактивно, в ином случае она считывает их из job.params в папке  сборки, который формируется в момент подготовки сборки из параметров  заданных ранее при помощи setparam и параметров задачи по-умолчанию.

Планировщик задач использует два исполняемых файла - один для  непосредственно запуска задач, второй для добавления, удаления и  изменения запланированных задач. Для оповещения процесса о изменении  списка задач используется системная условная переменная из  Boost.Interprocess.

Логирование реализовано при помощи библиотеки scf::logger.

Ядро покрыто модульными тестами с применением библиотеки GTest.

WebUI

Событийный цикл приложения и сетевая часть реализованы при помощи библиотеки Boost.Asio.

Публичный API представлен WebSocket с протоколом описанным выше, а  так же дополнительным HTTP интерфейсом для загрузки и скачивания файлов,  запуска задач посредством вебхук или curl. Данный API реализован с  помощью Boost.Beast.

Для работы с ядром используется библиотека Boost.Process.

Для хранения информации о пользователях и правах доступа использована СУБД SQLite и библиотека sqlite_orm.

Результат

Система успешно запущена в эксплуатацию на сайтах tomsksoft.

Да, столько времени у меня занял запуск простой демки на своем pet-project (другое дело, что демка вышла бесполезной, но об этом позже). Имеем: linux со всякими стандартными штуками для разработки и небольшой проект для доступа к БД, написанный на Qt (проект собирается как на CMake, так и на QMake, не знаю зачем так). Делаем все максимально лениво, поэтому вместо сборки чего-то руками, тупо скачаем Qt for WebAssembly c помощью online-установщика (поди вспомни еще свой аккаунт в Qt). Я взял последний Qt 5.15, ставим на скачивание, идем читать доку.

Сразу же напрягло отсутствие Widgets в списке поддерживаемых модулей на wiki-странице, но и в списке не поддерживаемых я тоже его не нашел, так что будем надеяться, что оно заработает (спойлер: оно заработает). Список поддерживаемых модулей:
* qtbase
* qtdeclarative
* qtquickcontrols2
* qtwebsockets
* qtsvg
* qtcharts
* qtmqtt

На той же вики я прочитал, что для Qt 5.15 лучше всего подходит Emscripten SDK версии 1.39.8. Что ж, его и возьмем =)
Вскользь прочитал, что там какая-то беда с многопоточностью, но потоки я завести еще не успел (лень-матушка), с довольной ухмылкой идем дальше.

Давайте поставим уже этот Emscripten SDK, чем бы он ни был:

$ git clone https://github.com/emscripten-core/emsdk.git
$ cd emsdk/
$ ./emsdk install 1.39.8
$ ./emsdk activate 1.39.8

Видим такую подсказку в выводе:

- To conveniently access emsdk tools from the command line,
  consider adding the following directories to your PATH:
    /home/ieo/Documents/projects/emsdk
    /home/ieo/Documents/projects/emsdk/node/12.18.1_64bit/bin
    /home/ieo/Documents/projects/emsdk/upstream/emscripten
- This can be done for the current shell by running:
    source "/home/ieo/Documents/projects/emsdk/emsdk_env.sh"
- Configure emsdk in your bash profile by running:
    echo 'source "/home/ieo/Documents/projects/emsdk/emsdk_env.sh"' >> $HOME/.bash_profile
    

Выберем первый способ (хватит же на попробовать):

$ source ./emsdk_env.sh

Проверим, что все встало:

$ em++ --version
<...>
emcc (Emscripten gcc/clang-like replacement) 1.39.8 (commit 60e3a51c7ba8bb96a47d06280b0b1f8ef711608b)

Видим нужную нам версию в выводе, как-то даже слишком просто, чувство незаслуженной гордости требует двигать дальше.

Давайте сперва проверим, что Qt вообще запустится в браузере (ага, онлайн демку с их сайта то нельзя запустить). Отрубаем в проекте через опции сборки все, кроме UI на Qt (хорошо, что эти опции есть), что также исключит из сборки кучу библиотек, с ними разберемся позже (нет).
Дока по emscripten предлагает использовать ./emconfigure и ./emmake вместо сами поняли чего, однако Qt предлагает вызывать qmake из папочки, куда мы поставили Qt WebAssembly. Разбираться со сборкой через CMake что-то лень, да и отпуск у меня, QMake так QMake =)

$ cd .. && mkdir build && cd build
$ ~/Qt/5.15.0/wasm_32/bin/qmake ../project_name

Собираем:

$ make -j4

Собралось! Запускаем встроенный в emsdk простецкий веб-сервер, который засунули в папочку emsdk, указываем ему путь до проекта:

$ emrun --no_browser --port 8080 ~/Documents/projects/project_name/project_name.html

Открываем в FireFox ссылочку: http://localhost:8080/project_name.html (вы можете открыть демку здесь)

It works! (помните, так apache говорил?) Скрин диалога из лисицы и нативное окно для сравнения:

Как видим, работают стандартные виджеты QDialog, QComboBox, QSpinBox и тд и все это без изменения Qt кода вообще (хотя чего-то не сохраняется в QSettings).

Давайте поглядим что получилось на выходе по размеру (жЫр, но я ждал под сотню метров):

2,8K project_name.html
298K project_name.js
13M  project_name.wasm
22K  qtloader.js

Раскупориваем либу для доступа к БД (-lmysqlclient) и ... что-то не собирается. Значит, настало время читать инструкции.

В документации я прочитал про следующие ограничения/особенности WASM:

0. Библиотеки.

Нужно собрать либы самому в bitcode. Нельзя просто так взять и войти в Мордор готовую либу (*.a. *.so) с вашей нативной системы (ну, логично), нужно собрать ее в байткод, либо воспользоваться портом (если вам повезло и он есть).

Спортированные либы, кт нам понадобятся (нет):

• libc/libc++
• zlib

Список всех портов https://github.com/emscripten-ports

Еще я нашел такие (интересные для меня) порты:

• ffmpeg https://github.com/Kagami/ffmpeg.js
• FANN https://github.com/louisstow/fann.js
• OpenCV https://docs.opencv.org/3.4/d5/d10/tutorial_js_root.html

1. Динамическое связывание

Динамические библиотеки (.so) поддерживаются (конечно же собранные в байткод!), но на финальном этапе сборки при генерации JS они будут слинкованы как статические. Более того, компилятор emcc игнорирует комманды по линковке динамических либ при линковке биткода (т.е. не на финальной стадии), чтобы избежать злосчастной проблемы с дубликатами символов. (на этом моменте я с ужасом вспоминаю, как когда-то давно на iOS из-за ограничений App Store приходилось статически линковать кучу библиотек и однажды возник конфликт BoringSSL и OpenSSL).

2. Неподдержка TCP

И тут внезапно (нет) выяснилось, что браузеры не поддерживают прямой доступ к TCP сокетам, нужный для работы mysqlclient, да и других сетевых клиентов для БД, да и много для чего еще. Emscripten пытается решить эту проблему эмулированием работы Posix Sockets API через WebSocket (они-то конечно же в браузере работают), но это означает, что на стороне сервера нужно делать мост в обратном направлении (делать из WebSocket TCP), что конечно же крайне непоходящее решение.

Можно конечно же взять и попробовать chrome.sockets.tcp и какой-нибудь драйвер поверх него, но это доступно только в расширениях Chrome и то со специальными пермишнами (FIXME). Облом! UPD: уже после заметил, что "сырые" сокеты прямо в браузере сейчас под обсуждением.

Выводы

Итак, Qt в браузере через WebAssembly заработало, но сделать полезное приложение у меня не получилось из-за ограничений браузера. Веб-разработчики героически пытаются писать полезные приложения, но нативщина никуда не делась и надеюсь не денется.