futriix/README.md

<!-- Improved compatibility of К началу link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
<a id="readme-top"></a>
<!--
*** Thanks for checking out the Best-README-Template. If you have a suggestion
*** that would make this better, please fork the repo and create a pull request
*** or simply open an issue with the tag "enhancement".
*** Don't forget to give the project a star!
*** Thanks again! Now go create something AMAZING! :D
-->


<!-- PROJECT LOGO -->
<br />
<div align="center">
<!--  <a href="https://github.com/othneildrew/Best-README-Template"> -->
<img src="Logo-Futriix.png" height=100></img>
  </a>

  <h3 align="center">Futriix</h3>

  <p align="center">
   Проект Futriix основан на базе проекта KeyDB <br>
   Futriix's (команды futriix по большей части совпадают с командами KeyDB)
    <br />
    <a href="https://docs.keydb.dev/"><strong>Изучить полную документацию</strong></a>
    <br />
    <br />
  <!--   <a href="">Сообщить об ошибке</a> 
    &middot;
 <!--    <a href="">Предложение новой функциональности</a> -->
  </p>
</div>

  ## Краткая документация проекта Futriix

<!-- TABLE OF CONTENTS -->
<br>
<!-- <details> -->
  <summary><b>Содержание</b></summary></br>
  <ol>
     <li>
      <a href="#о-проекте">О проекте</a>
      <li><a href="#лицензия">Лицензия</a></li>
      <li><a href="#основные-термины">Основные термины</a></li>
      <li><a href="#подготовка">Подготовка</a></li>
      <li><a href="#компиляция">Компиляция</a></li>
      <li><a href="#тестирование-сборки">Тестирование сборки</a></li>
      <li><a href="#пример-основных-команд">Пример основных команд</a></li>
      <li><a href="#кластер">Кластер</a></li>
      <li><a href="#типовые-проблемы">Типовые проблемы</a></li>
      <li><a href="#дорожная-карта">Дорожная карта</a></li>
      <li><a href="#вклад">Вклад</a></li>
      <li><a href="#контакты">Контакты</a></li>
  </ol>
<!-- </details> -->

<!-- ABOUT THE PROJECT -->
## О проекте

Futriix - распределённая СУБД с поддержкой модулей на базе Искусственного Интеллекта (ИИ) и плагинов на языке Golang, является форком KeyDB.
Futriix является резидентной субд, т.е. хранящей свои данные в оперативной памяти, с их периодическим сохранением на внутренний носитель: HDD (жёсткий диск) или SSD-накопитель.

### Отличия futriix от KeyDB

* Улучшен скрипт сборки кластера `cluster.sh` (добавлена цветовая, текстовая индикация состояния сборки кластера) 
* Полностью удалена поддержка `Sentinel`
* Добавлены модули поддержки SQL, внешнего запуска команд unix и JSON-модуль
* Реализован интеллектуальный помощник (на базе ИИ), осуществляющий поиск по документации

<!-- LICENSE -->
## Лицензия

Проект распространяется под 3-пунктной лицензией BSD. Подробнсти смотрите в файле `COPYING.txt`.

## Основные термины

* **База Данных(БД)** -массив информация, хранящийся, например, на флешке, в файле, на кластере  
* **Система Управления Базами Данных(СУБД)** - Это программа для внесения изменений в базу данных и поиска по ней
* **Резидентная СУБД** - субд, хранящая все свои данные в оперативной памяти, с периодическим сохранением на HDD или SSD
* **Инстанс** - запущенный экземляр базы данных
* **Узел (хост,нода)** - физический сервер
* **Кластер** - группа компьютеров, объединённых высокоскоростными каналами связи и представляющая с точки зрения пользователя единый аппаратный ресурс
* Команды, выполняемые с привилегиями суперпользователя (root), отмечены символом приглашения **«#»**
* Команды, выполняемые с правами обычного пользователя(user), отмечены символом приглашения **«$»**
* **FutBot** - интеллектуальный помощник в мессенджере Телеграмм, помогающий осущесвлять быстрый поиск по документации проекта


## Подготовка

**Для операционных систем семейства Debian** выполните следующие шаги:
* Устанавливаем язык программирования C/C++, соопутствующие утилиты (autoconf и другие)

  ```sh
   # apt update
   # apt upgrade
   # apt install build-essential nasm autotools-dev autoconf libjemalloc-dev tcl tcl-dev uuid-dev libcurl4-openssl-dev cmake git hugepages
  ```

**Для операционных систем семейства Red Hat (Fedora, Aurora)** выполните следующие шаги:
* Устанавливаем язык программирования C/C++, соопутствующие утилиты (autoconf и другие)

  ```sh
   # dnf update
   # dnf install -y jemalloc-devel g++ libuuid-devel libatomic openssl-devel curl-devel cmake git hugepages
  ```

* Устанавливаем язык программирования Golang по инструкции с [официального сайта](https://go.dev/doc/install)

**Для операционной системы Alpine** выполните следующие шаги:
* Устанавливаем язык программирования C/C++, соопутствующие утилиты (autoconf и другие)

  ```sh
   # apk update
   # apk add --no-cache coreutils gcc linux-headers make musl-dev util-linux-dev openssl-dev curl-dev g++ bash git perl libunwind-dev
  ```

* Устанавливаем язык программирования Golang по инструкции с [официального сайта](https://go.dev/doc/install) 
  

## Компиляция

1. Копируем репозиторий
   ```sh
    $ git clone https://source.futriix.ru/gvsafronov/futriix
   ```
2. Переходим в каталог с исходном кодом src
   ```sh
    $ cd src/
   ```   
3. Компилируем Futriix с помощью утилиты Make
   ```sh
   $ make
   ```  

> [!WARNING]  
> **Futriix также может быть скомпилирован для следующих операционных систем: `Linux`, `OSX`, `Open Indiana`, `FreeBSD`, но сборка для этих операционных систем не проводилась!!!**


### Дополнительные параметры компиляции

Для сборки проекта с поддержкой TLS выпоните команду:
   ```sh
    $ make BUILD_TLS=yes
   ```
Для сбоки проекта с поддержкой TLS, в качестве модуля, выполните команду:
   ```sh
    $ make BUILD_TLS=module
   ```
Для выполнения данной операции вам необходимо библиотека OpenSSL (например,
libssl-dev для Debian/Ubuntu).

<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Тестирование сборки

После компиляции Futriix, рекомендуем запустить утилиту для проверки корректности сборки:
   ```sh
    $ make test
   ```
> [!TIP]  
> **Исправление проблем сборки с зависимостями или кэшированными параметрами сборки**  
> Futriix содержит некоторые зависимости, которые хранятся в директории `deps`.
> Утилита `make` автоматически не пересобирает зависимости даже если вносятся каие-либо изменения в код зависимостей.

Когда вы обновляете код проекта командой `git pull` или когда код внутри
дерева зависимостей изменен каким-либо другим способом, обязательно используйте следующее
команду для того, чтобы действительно все почистить и пересобрать с нуля:

   ```sh
    $ make distclean
   ```
В результате работы команды выше будут очищены: аллокатор памяти jemalloc, язык lua, библиотеку hiredis, библиотеку linenoise а также другие зависимости.

Кроме того, если вы принудительно используете определенные параметры сборки, такие как 32-битная версия для 32-битной системы, оптимизации компилятора C в данном случае не будут выполнены. Оптимизации (для целей отладки) и другие подобные параметры времени сборки,
кэшируются на неопределенный срок, пока вы не выполните команду `make distclean`.

<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Аллокатор

Выбор аллокатора памяти не по умолчанию при сборке Futriix выполняется путем установки
параметра `MALLOC` переменной окружения. Futriix компилируется и компонуется с libc
malloc по умолчанию, за исключением jemalloc, который используется по умолчанию в дистрибутивах Linux.
Это значение по умолчанию было выбрано потому, что в jemalloc меньше
проблем c фрагментацией, чем libc malloc.

Чтобы принудительно скомпилировать libc malloc, выполните следующую команду:
   ```sh
    $ make MALLOC=libc
   ```
Для компиляции аллокатора jemalloc на операционной системе Mac OS X, выполните команду:

   ```sh
    $ make MALLOC=jemalloc
   ```

<!-- USAGE EXAMPLES -->
## Пример основных команд
В данном разделе приведён пример основных команд субд Futriix

Запускаем клиент Futriix, перейдя в каталог с исходным кодом:
   ```sh
    $ cd src && ./futriix-cli
   ```

Проверяем доступность сервера, выполняяя команду `ping`, если будет получен ответ `pong`-значит сервер доступен и работает корректно
   ```sh
    127.0.0.1:futriix:~> ping
    PONG
   ```
Присваеваем значение переменной `foo` равное `bar`, командой ниже:
   ```sh
     127.0.0.1:futriix:~> set foo bar
     OK
   ```

Получаем значение переменной `foo`, командой ниже:
   ```sh
    $ get foo
    "bar"
   ```

<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Кластер

1. Откройте директорию с Futriix:
   ```sh
    $ cd futriix
   ```   
2. Откройте файл конфигурации futriix.conf в любом текстовом редакторе, например nano, как в примере приведённом ниже:
   ```sh
    $ nano futriix/futriix.conf
   ``` 
3.  Проверьте, установлены ли значения "yes" для параметров "active-replica" и "multi-master" в файле конфигурации `futriix.conf`
    После чего добавьте в файл конфигурации ip-адреса, узлов вашего кластера. 
    Если вы всё сделали правильно у вас должны отобразится строки в файле конфигурации `futriix.conf` как показано ниже:
     ```sh
      active-replica yes
      multi-master yes
      replicaof 192.168.11.5 9880
      replicaof 192.168.11.6 9880
      replicaof 192.168.11.7 9880
     ```
4. Сохраните внесённые вами изменения, выйдите из редактора, воспользовавшись командами ниже:
   ```sh
    $ ctrl+O
    $ ctrl+x
   ```   
5. Перейдите в директорию Futriix и запустите скрипт `cluster.sh` с параметрами `pick` (скрипт запущенный с данным параметром "соберёт кластер"), и `run`,(скрипт запущенный с данным параметром "запустит кластер")  как указано ниже:
   ```sh
    $ ./cluster pick
    $ ./cluster run
   ```
6. Для остановки кластера запустите скрипт `cluster.sh` с параметром `stop` 
   ```sh
    $ ./cluster stop
   ```   
<p align="right">(<a href="#readme-top">К началу</a>)</p>

## Типовые проблемы

В данном разделе описаны типовые проблемы, возникающие при эксплуатации субд Futrix.

1. **Описание проблемы:** При запуске инстанса futriix, появляется следующее сообщение:
   ```sh
    Warning: no config file specified, using the default config. In order to specify a config file use ./futriix-server /path/to/futriix.conf
   ```

**Решение:**

При запуске инстанса сервера futriix, указать корректный путь до файла конфигурации, командой ниже:
```sh
 $ ./futriix-server /path/to/futriix.conf
```   

2. **Описание проблемы:** При запуске инстанса Futriix, появляется следующее сообщение:
    ```sh
     1:12:S 18 Apr 2025 04:47:25.643 # NOTICE: Detuning locks due to high load per core: 97.49%
     1:12:S 18 Apr 2025 04:47:55.491 # NOTICE: CPU pressure reduced
    ```

**Решение:**

Это штатная ситуация, и она не является ошибкой и не вызывает проблем. Суть этого сообщения в том, что futriix пытается корректно обработать ситуацию с превышением нагрузки на ЦП. 

Futriix использует спинлоки для быстрой синхронизации. Когда нагрузка на ЦП превышает 100% на ядро, ядро может неосознанно предоставить время ЦП заблокированному потоку, который находится в состоянии ожидания, вместо активного потока. Это приводит к значительно большей задержке.

Когда такая ситуация обнаруживается, Futriix будет крутиться в ожидании меньшего времени, прежде чем приостановить поток. Это приводит к лучшей пропускной способности, когда время ЦП ограничено. Однако «правильным» решением является обеспечение того, чтобы время ЦП не было так ограничено.

<p align="right">(<a href="#readme-top">К началу</a>)</p>

<!-- ROADMAP -->
## Дорожная карта

- [x] Добавить поддержку хранимых процедур
- [x] Добавить поддержку многопоточности
- [x] Изменить приглашение командной строки клиента futriix-cli
- [x] Добавить в скрипт cluster.sh, формирующий кластер Futriix, цветовые текстовые индикаторы состояния процесса с левой стороны
- [x] Добавить поддержку модуля для работы с JSON
- [x] Удалить поддержку Sentinel
- [x] Добавить поддержку хранимых процедур
- [x] Добавить поддержку языка запросов SQL
- [x] Добавить поддержку запуска внешних команд ОС из субд
- [x] Добавить макет интеллектуального помощника FutBot
- [ ] Реализовать поддержку алгоритма Raft
- [ ] Реализовать поддержку роли Podman для автоматического развёртывания кластера в виртуальной среде
- [ ] Реализовать планировщик задач,основанный на вытесняющей многозадачности
- [ ] Реализовать поддержку ACID-транзакций
- [ ] Реализовать полноценного интеллектуального помощника FutBot, задачами которого будут быстрый поиск ответов на вопросы, возникающие при эксплуатации субд Futrix.

См. [Открытые проблемы](https://source.futriix.ru/gvsafronov/futriix/issues) полный список предлагаемых функций (и известных проблем).

<p align="right">(<a href="#readme-top">К началу</a>)</p>

<!-- CONTRIBUTING -->
## Вклад

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

Если у вас есть предложение, которое могло бы улучшить ситуацию, создайте форк репозитория и создайте запрос на включение. Также можно просто открыть задачу с тегом «улучшение».


1. Форкните проект
2. Создайте свою ветку функций (`git checkout -b Feature/AmazingFeature`)
3. Зафиксируйте свои изменения (git commit -m 'Add some AmazingFeature'`)
4. Отправьте в ветку (`git push main Feature/AmazingFeature`)
5. Откройте запрос на включение

<!-- CONTACT -->
## Контакты

Григорий Сафронов - [E-mail](gvsafronov@yandex.ru) 

Ссылка на Интеллектуальный помощник - [FutBot](https://t.me/Futriix_bot)

<p align="right">(<a href="#readme-top">К началу</a>)</p>