JDBC-коннектор

Можно брать в работу

Бизнес-требования

Основные требования к фиче:

• Добавить подключение диспетчере данных – JDBC-коннектор
• Возможность добавлять новые коннекторы к любой СУБД прямо из интерфейса системы
• Возможность управлять параметрами подключения через конфигурацию источника
• Обеспечить безопасность соединения
• Сохранить логику взаимодействия с микросервисами бэкенда, просмотр статуса подключения
• Настроить логирование всех операций с JDBC-коннекторами
• Коннектор и нагрузка на него никак не должны влиять на производительность системы, при падении драйвера не должен падать основной поток FB
• В документации требуется добавить новый раздел, посвященный добавлению JDBC-драйвером и подключению по JDBC к внешним СУБД

План работ

• Управление драйверами (бэкенд)
  • Подготовить каталог для хранения jar-файлов драйверов с правами доступа только для сервисов платформы; обеспечить резервное копирование этого каталога
  • Настроить валидатор драйверов: проверить наличие обязательных мета-методов (getTables, getColumns, getImportedKeys, getColumnName, getColumnType, getScale, getColumnCount); обеспечить логирование результатов валидации
  • Обеспечить регистрацию драйвера в реестре: записать тип, версию, хэш-сумму (?), дату загрузки, статус
  • Настроить хранение лицензионных ключей драйверов БД; обеспечить проверку наличия лицензии при регистрации драйвера
• Управление драйверами (фронтенд)
  • Реализовать интерфейс загрузки драйвера: выбор файла, ввод типа СУБД, версии, описания; обеспечить проверку файла
  • Реализовать вывод списка доступных драйверов в интерфейсе настройки источников
• Конфигурация подключений (бэкенд)
  • Настроить хранение учётных данных в хранилище с обратимым шифрованием; обеспечить передачу секретов микросервисам только в момент выполнения подключения
  • Реализовать модуль тестирования подключения: при нажатии «Проверить» микросервисы пытаются установить соединение с внешней БД и выполнить пробный запрос; обеспечить возврат понятного сообщения об успехе или ошибке
  • Реализовать поддержку параметров SSL: загрузка сертификата сервера, настройка взаимной аутентификации при необходимости; обеспечить проверку валидности сертификата при тестировании подключения
  • Реализовать поддержку SSH-туннеля: ввод хоста, порта, логина, пароля или ключа; обеспечить создание туннеля перед установкой JDBC-соединения и его закрытие после завершения
• Конфигурация подключений (фронтенд)
  • Реализовать форму создания источника данных: выбор драйвера из реестра, ввод JDBC URL, логина, пароля, настроек SSL/SSH; обеспечить маскировку пароля в интерфейсе
• Загрузка данных (бэкенд)
  • Реализовать логику Cron: запуск загрузок по расписанию или событию; обеспечить передачу контекста выполнения в Blocker и обработку ошибок запуска
  • Реализовать логику Blocker: проверка активной загрузки для того же источника; обеспечить установку и снятие блокировки, предотвращение параллельного импорта одной таблицы
  • Реализовать логику Loader: чтение данных из внешней БД через JDBC-драйвер с учётом параметров подключения
  • Настроить запись данных в ClickHouse
• Ролевая модель (бэкенд)
  • Доступ к добавлению и валидации драйверов имеют только пользователи с ролью "Администратор системы"
  • Доступ к созданию подключений имеют только пользователи с ролью "Разработчик" и выше

Интеграционная схема

Общие сценарии использования

Критерии приёмки

Обязательно проверить все сценарии использования в каждом разделе!

Решение

Управление драйверами

Системная логика (бэкенд)

План работ:

• Подготовить каталог для хранения jar-файлов драйверов с правами доступа только для сервисов платформы; обеспечить резервное копирование этого каталога
• Настроить валидатор драйверов: проверить наличие обязательных мета-методов; обеспечить логирование результатов валидации
• Обеспечить регистрацию драйвера в реестре: записать тип, версию, путь к файлу, хэш-сумму (?), дату загрузки, статус
• Настроить хранение лицензионных ключей драйверов в БД; обеспечить проверку наличия лицензии при регистрации драйвера

Реестр драйверов:

• Требуется обеспечить хранение jar-файлов в системном хранилище (например, в серверном хранилище)
• Требуется обеспечить хранение параметров драйверов в системном хранилище (например, в PG):
  • id записи
  • Путь к файлу драйвера в хранилище
  • Тип – текст
  • Версия СУБД – текст
  • Описание – текст
  • Статус – текст
• Требуются методы для:
  • Передачи jar-файлов с фронтенда
    • POST-запрос
    • Передает в себе:
      • Файл драйвера
      • Тип – текст
      • Версия СУБД – текст
      • Описание – текст
    • Должна быть выполнена проверка валидации файла (см. далее)
    • Должна быть проверка на роль пользователя – только администратор системы
  • Получения списка драйверов из хранилища
    • GET-запрос
      
    • Ничего не передает в себе
    • Ожидает в ответ список параметров файлов:
      • id записи из хранилища параметров
      • Тип – текст
      • Версия СУБД – текст
      • Описание – текст
      • Статус – текст
    • Должна быть проверка на роль пользователя – только администратор системы
  • Обновления jar-файлов в хранилище:
    • PATCH-запрос (ну или PUT, просто стараюсь соблюсти REST)
    • Передает в себе:
      • id записи из хранилища параметров
    • Может передавать в себе:
      • Файл драйвера
      • Тип – текст
      • Версия СУБД – текст
      • Описание – текст
    • При перезаписи файла должна быть выполнена проверка валидации как при добавлении файла
      • Если валидация пройдена, старый файл удаляется, вместо него добавляется переданный
    • Должна быть проверка на роль пользователя – только администратор системы
  • Удаления jar-файлов в хранилище:
    • DELETE-запрос
    • Передает в себе:
      • id записи из хранилища параметров
    • Удаляется и запись в хранилище параметров, и jar-файл в реестре драйверов согласно пути к файлу в хранилище параметров
    • Должна быть проверка на роль пользователя – только администратор системы

Валидатор драйверов:

Валидатор проверяет загружаемый .jar-файл JDBC-драйвера перед регистрацией в реестре. Его цель – не допустить в систему некорректные, повреждённые или небезопасные файлы.

• Требуется метод для вызова валидации файла:
  • POST-запрос
  • Передаёт в себе jar-файл
  • Должна быть проверка на роль пользователя – только администратор системы
• Метод обязательно вызывается при создании/редактировании драйвера
• Обязательно выполняются следующие проверки:
  • Расширение файла = .jar
  • MIME-тип = application/java-archive или application/zip
  • Неповрежденная структура файла
  • Размер файла < 100 MB
  • Наличие манифеста META-INF/MANIFEST.MF
  • Отсутствуют подозрительные классы
  • Цифровая подпись файла валидна (при наличии)
  • Хэш не в списке уязвимых
  • Файл уникален в реестре драйверов
• Обязательно выполняются проверки на наличие следующих мета-методов:
  • getTables,
  • getColumns,
  • getImportedKeys,
  • getColumnName,
  • getColumnType,
  • getScale,
  • getColumnCount
• Требуется защита от Java-инъекций (не должно быть ппропущено):
  • Вредоносный класс в .jar-файле (класс с static {} блоком, выполняющим код)
  • JNDI-инъекция через логи
  • Выполнение команд на основе ввода
  • SpEL, OGNL, JavaScript в конфиге
• Запрещенные параметры в JDBC URL:
  • allowLoadLocalInfile=true
  • allowMultiQueries=true
  • autoDeserialize=true
  • statementInterceptors
  • connectionInitSql
• Дополнительно могут выполняться другие проверки для защиты при загрузке файлов
• В случае ошибки необходимо возвращать на фронтенд текст "Валидация файла не пройдена. Ошибка:" + текст системной ошибки

Чек-лист проверок файла:

• Если валидация пройдена (нет ни одной ошибки со статусом "Критическая"), то:
  • В таблице параметров драйверов появляется новая запись с параметрами
  • Записи присваивается статус в зависимости от результатов проверки:
    • Если нет ни одной ошибки со статусом "Подозрительная" – статус "Активен"
    • Если есть хотя бы одна ошибка со статусом "Подозрительная" – статус "Требует проверки"
  • В реестр драйверов помещается файл драйвера

Пользовательский интерфейс

Расположение: Панель администратора → Настройки → Новая вкладка "JDBC-драйверы"

Вкладка доступна только пользователям с ролью "Администратор системы". Для всех остальных ролей вкладка отсутствует.

На вкладке:

• Кнопка "Добавить драйвер"
• Таблица драйверов, содержит в себе:
  • Название драйвера
  • Статус ("Принято" зеленого цвета, или "Требует проверки" желтого цвета)
  • Версия СУБД
  • Инфо
    
• При наведении на элемент списка появляются 2 кнопки: удалить ("корзина") и редактировать ("карандаш")
• Если в списке нет элементов, то нет и списка. В области остается только кнопка "Добавить драйвер"

При добавлении/редактировании драйвера открывается модальное окно:

• Название окна – "Добавление/редактирование драйвера"
• Поле ввода "Тип", по умолчанию пустое, обязательно для заполнения
• Поле ввода "Версия СУБД", по умолчанию пустое
• Область выбора файла с кнопкой "Выбрать файл"
• Кнопка "Добавить"
• Кнопка "Отмена"

Референс из AW BI:

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

• Название – "Удаление драйвера"
• Текст: "Вы уверены, что хотите удалить данный драйвер? Все существующие подключения, использующие драйвер для JDBC-подключений, не смогут обновлять данные"
• Кнопка "Удалить"
• Кнопка "Отмена"

Если драйвер не прошел валидацию, то появляется всплывающая ошибка при открытом окне создания/редактирования: "Валидация драйвера не пройдена: обнаружены критические нарушения безопасности или целостности файла"

Сценарии использования

Пользователь переходит на вкладку "JDBC-драйверы". В интерфейсе отображается список драйверов в виде раскрывающихся строк.

Пользователь нажимает на драйвер в списке. Раскрывается список параметров этого драйвера.

Пользователь нажимает на кнопку "Добавить драйвер". Открывается модальное окно добавления драйвера.

Пользователь нажимает в окне кнопку "Выбрать файл". Открывается filepicker для выбора файла с устройства. После выбора файл добавляется в окно в виде иконки файла с подписью в вдие названия файла. Кнопка "Выбрать файл" остается под файлом.

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

Пользователь наводит курсор на драйвер в списке. Появляются кнопки удаления и редактирования. 

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

Пользователь нажимает в окне на кнопку "Удалить". Драйвер удаляется из списка.

Пользователь нажимает на кнопку "Редактировать". Открывается окно редактирования драйвера. Сценарий изменения аналогичен сценарию добавления драйвера.

Системная логика (фронтенд)

При переходе на вкладку "JDBC-драйверы" выполняется GET-запрос на получение списка драйверов с бэкенда. В ответ приходит массив параметров:

• id записи из хранилища параметров
• Тип – текст, подставляется в качестве названий элементов списка
• Версия СУБД – текст, подставляется в список параметров при раскрытии элемента списка
• Описание – текст, подставляется в список параметров при раскрытии элемента списка
• Статус – текст, подставляется в список параметров при раскрытии элемента списка

При выборе файла в окне добавления/редактирования открывается filepicker. Доступны для выбора только файлы с расширением .jar. Можно выбрать ровно один файл. При повторном выборе файла в том же окне заменять старый файл на новый.

При добавлении драйвера выполняется:

• POST-запрос на валидацию драйвера. Передает в себе только файл драйвера. Если в ответ получает ошибку валидации, то выводить всплывающее сообщение с ошибкой с бэкенда.
• Если валидация пройдена, то выполняется POST-запрос на отправку параметров драйвера. Передаются введенные пользователем данные:
  • Файл драйвера
  • Тип – текст
  • Версия СУБД – текст
  • Описание – текст

При редактировании драйвера выполняется:

• POST-запрос на валидацию драйвера. Передает в себе только файл драйвера. Если в ответ получает ошибку валидации, то выводить всплывающее сообщение с ошибкой с бэкенда.
• Если валидация пройдена, то выполняется PATCH-запрос, который передает в себе все измененные параметры.

При удалении драйвера выполняется DELETE-запрос, который передает в себе id удаляемого драйвера.

Конфигурация подключений

Системная логика (бэкенд)

• Настроить хранилище учётных данных с обратимым шифрованием; обеспечить передачу секретов микросервисам только в момент выполнения подключения
• Реализовать модуль тестирования подключения: при вызове метода микросервисы пытаются установить соединение с внешней БД и выполнить пробный запрос; обеспечить возврат понятного сообщения об успехе или ошибке
• Реализовать поддержку параметров SSL: прием сертификатов, настройка взаимной аутентификации; обеспечить проверку валидности сертификата при тестировании подключения
• Реализовать поддержку SSH-туннеля: прием параметров хоста, порта, логина, пароля или ключа; обеспечить создание туннеля перед установкой JDBC-соединения и его закрытие после завершения
• Обеспечить регистрацию подключения в реестре: записать имя, тип драйвера, URL, зашифрованные учетные данные, настройки SSL/SSH, статус

• id записи
• Имя подключения – текст 
• ID драйвера – связь с реестром драйверов JDBC
• URL – текст
• Логин – текст
• Пароль – текст
• Настройки SSH:
  • Имя хоста – текст
  • Порт – число
  • Логин – текст
  • Пароль – текст 
• Настройки SSL:
  • Путь к файлу корневого сертификата
  • Путь к файлу клиентского сертификата
  • Путь к файлу с клиентским приватным ключом
    
• Дата последней проверки – дата/время

Также требуется хранить файлы:

• корневого сертификата
• клиентского сертификата
• с клиентским приватным ключом

В ответ на запрос GET back/api/v1/sources/list/ необходимо также возвращать все источники JDBC, доступные пользователю.

Обработка SSL:

• При получении данных проверить наличие корневого сертификата, если флаг SSL включен
• Сформировать файлы хранилищ с правами доступа только для текущего процесса 
• Записать полученные сертификаты и ключи во временные файлы
• Сгенерировать параметры для JDBC драйвера: пути к временным файлам, пароли к хранилищам
• Передать сгенерированные пути и параметры в загрузку

Обработка SSH:

• Инициализировать SSH-клиент в рамках сессии
• Выполнить подключение к SSH-серверу используя переданные учетные данные
• Выполнить аутентификацию
• Открыть туннель: связать свободный локальный порт на сервере приложения с парой <Внутренний хост БД>:<Внутренний порт БД>
• Получить фактический номер выделенного локального порта
• Сформировать строку JDBC URL, заменив оригинальный хост и порт на localhost и выделенный локальный порт
• Передать управление соединением и данные туннеля в модуль выполнения запроса Обеспечить разрыв SSH-соединения и закрытие туннеля сразу после завершения выполнения запроса или тестирования

Пользовательский интерфейс

Референс из AW BI:

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

Окно удаления подключения – стандартное окно:

Контекстное окно такого подключения аналогично контекстному окну подключения к БД:

Иконка такого подключения состоит из иконки БД с подписью JDBC:

Сценарии использования

Пользователь создает новый источник данных, выбирает тип "JDBC". Открывается окно ввода настроек подключения.

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

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

Пользователь включает SSH-туннель, вводит хост, порт, логин и пароль сервера. Пользователь снова нажимает «Проверить подключение». Система устанавливает туннель, проверяет соединение и возвращает успех.

После успешной проверки пользователь нажимает "Сохранить". Источник создан и добавлен в список слева.

Пользователь отменяет изменения и нажимает "Назад". Выполняется выход к окну выбора типа источника.

Пользователь редактирует JDBC-источник. Открывается окно редактирования, заполненное данными из БД.

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

Системная логика (фронтенд)

При проверке подключения выполняется POST-запрос на тестирование подключения. Передает в себе все введенные данные формы, включая файлы сертификатов и SSH-параметры. Если в ответ получает ошибку, выводить всплывающее сообщение с ошибкой с бэкенда. В случае успеха выводить всплывающее сообщение с текстом: "Тест соединения пройден успешно". Окно не закрывается.

При создании подключения выполняется POST-запрос на создание источника. Передает введенные пользователем данные:

• Имя подключения
• ID драйвера JDBC
• URL
• Логин
• Пароль
• Флаг activeSSL и файлы сертификатов (если включено)
• Флаг activeSSH и параметры туннеля (если включено)

Если в ответ приходит ошибка валидации (например, запрещенные параметры в URL или отсутствие драйвера), выводить всплывающее сообщение с ошибкой. Окно не закрывается, данные сохраняются в полях

При редактировании подключения выполняется GET-запрос на данные этого источника. Все полученные данные записываются в соответствующие поля окна. При сохранении, если валидация и тест пройдены, выполняется PATCH-запрос. Передает id записи и только измененные поля.

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

При удалении подключения выполняется DELETE-запрос, который передает в себе id удаляемой записи.

При открытии готового источника отправлять стандартный запрос GET back/api/v2/source/{sourceId}/tables.

При прокрутке готового источника отправлять стандартные запросы на превью N-строк.

Загрузка данных

Системная логика (бэкенд)

Логика работы событий по расписанию (cron) аналогична существующей логике загрузки по заданию:

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

Логика получения таблиц JDBC-источника (до загрузки в БД проекта):

• Собрать полную конфигурацию источника из БД
• Взять соответствующий JDBC-драйвер из реестра драйверов
• Инициализировать SSH-туннель и SSL-контекст согласно сохраненным настройкам (используя файлы сертификатов)
• Сформировать запрос на просмотр первых 30 строк из целевой БД
• Отдать эти 30 строк на фронт стандартным методом

Логика загрузки данных в скрипте (в БД проекта) полностью аналогична загрузке из БД, за исключением необходимости открывать в начале и закрывать в конце SSH-туннель (если он выбран).

Ролевая модель