Welcome to Apostol Web Service

Apostol Web Service

ОПИСАНИЕ

Apostol Web Service (AWS) - платформа, написанная на C++, для быстрого создания RESTful API сервисов под Linux, со встроенной поддержкой СУБД PostgreSQL.

Сервер приложений (API-сервер) — это неотъемлемая часть программного комплекса, построенного на базе трехзвенной архитектуры, которая содержит в себе бизнес-логику проекта. Программисту, разрабатывающему сервер приложений, в первую очередь нужно решить ряд ключевых моментов, без которых сервер приложений не может являться таковым: определиться с протоколом передачи данных (разработать свой на базе IP или выбрать стандартный - HTTP), наладить связь с базой данных, протоколирование (log), настройки (config) и реализовать всё это в виде системной службы - задача не из лёгких. Очевидным решением для многих является разработка сервера приложений на динамическом языке программирования (Perl, Python, Ruby), но такие решения не приспособлены для высоких нагрузок. AWS написан на C++ с применением асинхронной модели программирования специально для высоконагруженных систем.

Преимущество при программировании на C++: Программисту, который реализует логику веб-сервиса, не нужно вникать в особенности работы мультиплексированного ввода-вывода, функций обработки сигналов Linux (для построения системной службы) и тонкостях реализации асинхронной работы с PostgreSQL. AWS всё это скрывает, позволяя разработчику сконцентрировать своё внимание только на реализации бизнес-логики самого веб-сервиса.

Преимущество при программировании на PL/pqSQL: Программисту не знакомому с программированием на C++ AWS также будет интересен. Всю бизнес-логику веб-сервиса можно реализовать на PL/pqSQL, а AWS использовать в качестве транспорта.

АЛГОРИТМ РАБОТЫ

Apostol Web-Service состоит из двух серверов - HTTP сервера и PostgreSQL сервера.

HTTP сервер.

HTTP-сервер реализован на базе epoll API. Сервер работает в асинхронном режиме и имеет модульную конструкцию. Каждый модуль это независимый друг от друга участок кода с алгоритмом (бизнес логикой) обработки поступающих запросов. При поступлении корректного HTTP запроса сервер сверяет значение заголовка User-Agent с именем модуля. При совпадении запрос направляется и обрабатывается соответствующим модулем превращая апостол в веб-сервис. При отсутствии совпадения запрос направляется в модуль «WebServer» превращая апостол в веб-сервер. Таким образом HTTP-сервер может одновременно принимать запросы к множеству веб-сервисов.

PostgreSQL сервер.

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

Взаимодействие с базой данных происходят в асинхронном режиме, т.е. сервер не ждет, когда SQL запрос будет обработан, он лишь «дает команду» на его исполнение и тут же переходит к обработке других запросов от других клиентов при наличии таковых. Само клиентское приложение во время выполнения SQL запроса может или отключиться от сервера и выполнять какие-либо свои действия, или «висеть» и ждать завершения запроса. После того как SQL запрос будет выполнен, сервер принимает данные и если клиент не отключился выдает их клиентскому приложению, в противном случае сохраняет результат SQL запроса для того, что-бы клиентское приложение могло забрать данные в дальнейшем. Таким образом и сам клиент с сервером может работать как в синхронном, так и в асинхронном режиме.

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

ЛИЦЕНЗИЯ

Apostol Web-Service распространяется бесплатно по лицензии GNU General Public License v3.0, что обязывает программное обеспечение, разработанное на базе AWS, распространять на тех же условиях и не позволяет включать AWS в проприетарное программное обеспечение. Для тех, кого не устраивает лицензия GPL-3.0, предусмотрен вариант на платной основе с иным лицензионным соглашением.

Техническая поддержка по лицензии GPL-3.0 возможна только по e-mail, также возможна платная консультация (на русском языке) по цифровым каналам связи с демонстрацией видео изображения рабочего стола.

Иные формы приобретения и технической поддержки Apostol Web-Service предоставляются в рамках договорных соглашений.

ПОДРОБНО

Платформа AWS построена на базе библиотеки libdelphi с применением асинхронной модели программирования.

Бинарный файл apostol - системная служба Linux (демон) в задачу которого входит запуск и поддержка работоспособности двух внутренних служб:

  1. Server (HTTP-сервер);
  2. PQServer (PostgreSQL-сервер).
При реализации apostol, вдохновение черпалось из исходных кодов nginx. Поэтому управление apostol схоже с управлением nginx, как следствие производительность и отказоустойчивость apostol на уровне nginx.

Server

Асинхронный HTTP сервер.

Принимает HTTP запросы от клиентов и в зависимости от значения в заголовке User-Agent распределяет их между модулями (модификациями). При отсутствии заголовка User-Agent или должного, в нём, значения направляет запрос в модуль Web-Server превращая AWS в Веб-сервер.

Асинхронная работа сервера реализована с помощью epoll API.

PQServer

Асинхронный PostgreSQL сервер.

Сервер создаёт пул подключений к СУБД Postgres и позволяет отправлять SQL запросы в асинхронном режиме. Указать диапазон минимального и максимального количества подключений к СУБД можно в файле конфигурации в секции [postgres]

Сервер построен на базе библиотеки libpq с применением асинхронных команд.

МОДУЛИ

Апостол спроектирован таким образом, что основной код отвечает:

  • за работу приложения в качестве системной службы;
  • реализацию протоколов TCP/IP, HTTP;
  • взаимодействие с СУБД Postgres.

Код реализующий логику того или иного сервиса находится отдельно от основного кода в расширениях (модулях).

Модуль - это класс C++ принимающий на входе данные от HTTP-сервера и PQ-сервера (PostgeSQL). Программисту, который реализует логику Веб-сервиса, не нужно вникать в особенности работы мультиплексированного ввода-вывода, функций обработки сигналов Linux (для построения демона) и тонкостях реализации асинхронной работы с PostgreSQL. Апостол всё это скрывает, позволяя разработчику сконцентрировать своё внимание только на реализации логики самого Веб-сервиса, разрабатывая код в привычном для него стиле. Точками соприкосновения с Апостол будут только входящие и исходящие структуры данных.

Чтобы создать новый модуль нужно выполнить:

  1. Собрать проект, как описано ниже;
  2. В директории mod/ создать папку с названием Вашего модуля;
  3. В директории с названием Вашего модуля создать, с аналогичным названием, файлы MyModuleName.cpp/.hpp;
  4. В заголовочном файле MyModuleName.hpp объявить класс C++ производный от класса CApostolModule:
  5. В Mudules.hpp, после класса CApostolModule, добавьте заголовочный файл Вашего модуля #include "MyModuleName/MyModuleName.hpp"
  6. В Mudules.hpp найдите функцию CreateModule и добавьте условие вызова Вашего модуля согласно значения в User-Agent.

Всё!

Пример объявления класса class MyModuleName:

        class MyModuleName: public CApostolModule {
        private:

        protected:

            void DoPostgresQueryExecuted(CPQPollQuery *APollQuery) override {

            };

            void DoPostgresQueryException(CPQPollQuery *APollQuery, Delphi::Exception::Exception *AException) override {

            };

        public:

            MyModuleName(): CApostolModule() {};

            ~MyModuleName() override = default;

            static class MyModuleName *CreateModule() {
                return new MyModuleName();
            }

            void Execute(CHTTPConnection *AConnection) override {

            };

        };

СБОРКА

Для сборки проекта Вам потребуется:

  1. Компилятор C++;
  2. CMake или интегрированная среда разработки (IDE) с поддержкой CMake;
  3. Библиотека libpq-dev (libraries and headers for C language frontend development).
  4. Библиотека postgresql-server-dev-10 (libraries and headers for C language backend development)
Описание установки C++, CMake, IDE и иных компонентов необходимых для сборки проекта не входит в данное руководство.

Для сборки Апостол, необходимо:

  1. Скачать Апостол по ссылке;
  2. Распаковать;
  3. Скомпилировать (см. ниже).

Для сборки Апостол, с помощью Git выполните:

git clone https://github.com/ufocomp/apostol.git
Сборка:
cd apostol
cmake -DCMAKE_BUILD_TYPE=Release -G "CodeBlocks - Unix Makefiles" . -B cmake-build-release
cmake --build cmake-build-release --target apostol -- -j 4

УСТАНОВКА

Для установки Апостол нужно выполнить:

sudo cmake --build cmake-build-release --target install -- -j 4

По умолчанию Апостол будет установлен в:

/usr/sbin

Файл конфигурации и необходимые для работы файлы будут расположены в:

/etc/apostol

ЗАПУСК

Апостол - системная служба (демон) Linux. Для управления Апостол используйте стандартные команды управления службами.

Для запуска Апостол выполните:

sudo systemctl start apostol

Для проверки статуса выполните:

sudo systemctl status apostol

Результат должен быть примерно таким:

sudo systemctl status apostol
● apostol.service - LSB: starts the apostol web service
   Loaded: loaded (/etc/init.d/apostol)
   Active: active (running) since Sun 2019-04-07 01:42:54 MSK; 21h ago
   CGroup: /system.slice/apostol.service
           ├─26772 apostol: master process /usr/sbin/apostol
           └─26773 apostol: worker process (apostol)

Управление apostol.

Управлять apostol можно с помощью сигналов. Номер главного процесса по умолчанию записывается в файл /usr/local/apostol/logs/apostol.pid. Изменить имя этого файла можно при конфигурации сборки или же в apostol.conf секция [daemon] ключ pid.

Главный процесс поддерживает следующие сигналы:

Сигнал Действие
TERM, INT быстрое завершение
QUIT плавное завершение
HUP изменение конфигурации, запуск новых рабочих процессов с новой конфигурацией, плавное завершение старых рабочих процессов
WINCH плавное завершение рабочих процессов

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

Сигнал Действие
TERM, INT быстрое завершение
QUIT плавное завершение