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">
   <b>Проект futriix это мультимодельная NOSQL субд с очередями без блокировок</b> <br>
    <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="#http-api">HTTP API</a></li>
      <li><a href="#lua-скрипты">Lua-скрипты</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 это мультимодельная NOSQL субд без блокировок написанная на языке программирования Rust.
Поддерживает следующие модели хранения данных: модель временных рядов (time series), документную, ключ-значение.
Для расщирения базового функционала имеет встроенный lua-интепретатор.
Futriix является резидентной субд, т.е. хранящей свои данные в оперативной памяти, с их периодическим сохранением на внутренний носитель: HDD (жёсткий диск) или SSD-накопитель.


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

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

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

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


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

**Для операционных систем семейства Debian** выполните следующие шаги:
* Устанавливаем язык программирования Rust

  ```sh
   # apt update
   # apt upgrade
   # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```

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

  ```sh
   # dnf update
   # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```

**Для операционной системы Alpine** выполните следующие шаги:
* Устанавливаем язык программирования Rust

  ```sh
   # apk update
   # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```

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

1. Копируем репозиторий
   ```sh
    $ git clone https://source.futriix.ru/gvsafronov/futriix
   ```
2. Переходим в каталог с исходном кодом src
   ```sh
    $ cd futriix/
   ```   
3. Компилируем Futriix с помощью пакетного менеджера `Cargo`
   ```sh
   $ cargo build
   ```  
4. Запускаем серверв futriix'а с помощью команды `./futriix`
   
    ```sh
   $ ./futriix 
   
   Futriix Server started successfully!
   18:18:58 [INFO] Starting server on 127.0.0.1:8080
   18:18:58 [INFO] Log file: logs/futriix_21.07.2025 21-18-58.log
   18:18:58 [INFO] Symlink: futriix.log
   18:18:58 [INFO] Starting server on 127.0.0.1:8080
   18:18:58 [INFO] Server::run; addr=0.0.0.0:8081
   18:18:58 [INFO] listening on http://0.0.0.0:8081
   18:18:58 [INFO] Futriix Server started successfully!
   18:18:58 [INFO] Listening on: 127.0.0.1:8080
   18:18:58 [INFO] HTTP API available on: 0.0.0.0:8081
   ````  


5. Для запуска тестов запускаем команды:
   ```sh
   $ cargo test --test integration  # запуск только интеграционных тестов
   $ cargo test --bench benches    # запуск только бенчмарков
   ```  

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

<!-- USAGE EXAMPLES -->
## Примеры основных команд

В данном разделе приведён пример основных команд субд Futriix

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

    Futriix CLI Client
    Connected to server at 127.0.0.1:8080
    Type 'help' for available commands

    futriix:~> insert user1 {"name": "Alice", "age": 25}

   ```

Проверяем доступность сервера, выполняяя команду `insert`, если будет получен ответ `successful`-значит вставка данных работает корректно

  ```sh  
futriix:~> insert user1 {"name": "Alice", "age": 25}
Insert successful
 ```  

Считываем значение таппла `user1` командой ниже `get`:
   ```sh
     futriix:~> get user1
{
  "age": 25,
  "name": "Alice"          
}

   ```

Изменим значение переменных `name`, `age`, командой ниже:
   ```sh
futriix:~> update user5 '{"name": "Alice Smith", "age": 26}' 
Update successful

   ```
Удалим весь таппл
   ```sh
   futriix:~> delete user1  
   Delete successful
   ```

   Посмотрим как работают транзакции (создание, откат, коммит)
   ```sh
  futriix:~> begin
  Transaction started

  futriix:~> insert user3 {"name": "Charlie", "age": 40}     
  Insert successful

  futriix:~> rollback
  Transaction aborted

  futriix:~> insert user3 {"name": "Peter", "age": 32} 

  futriix:~> commit
  Transaction committed
   ```
  Создадим индекс для поля `age` в таппле user3, а потом удалим его
  ```sh
  futriix:~> createindex age                        
  Index created on field 'age'

  futriix:~> dropindex age
  Index dropped
  ```

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

## Репликация

1. Включите репликацию в конфигурационном файле `futriix.config.toml`, установив enabled = true в секции [replication] в файле конфигурации
    `futriix.config.toml`
   ```sh
    [replication]
    enabled = false     # Включена ли репликация
    peer_nodes = []     # Список узлов для репликации (например ["192.168.1.2:8080"])
    sync_interval = 1000 # Интервал синхронизации в мс  
   ```   
2. Откройте файл конфигурации `futriix.config.toml` в любом текстовом редакторе, например nano, если вы всё сделали правильно, он должен выглядеть так:
   ```sh
    $ nano futriix/futriix.conf.toml
   ``` 
     ```sh
     [server]
     ip = "127.0.0.1"    # IP-адрес сервера (0.0.0.0 для доступа из сети)
     port = 8080         # Порт для TCP-сервера
     log_path = "futriix.log"  # Путь к лог-файлу

     [client]
     ip = "127.0.0.1"    # IP для клиента (обычно localhost)
     port = 8080         # Порт клиента (должен совпадать с серверным)

     [replication]
     enabled = false     # Включена ли репликация
     peer_nodes = []     # Список узлов для репликации (например ["192.168.1.2:8080"])
     sync_interval = 1000 # Интервал синхронизации в мс

     [http_api]
     enabled = true      # Включить HTTP API
     port = 8081         # Порт для HTTP API (обычно на 1 больше основного)

     ```
4. Сохраните внесённые вами изменения, после чего репликация будет доступна в субд, выйдите из редактора, воспользовавшись командами ниже:
   ```sh
    $ ctrl+O
    $ ctrl+x
   ```   
5.  Также для включения репликации вы можете использовать команду в `futriix-cli`:
     ```sh

    futriix:~> replication on
    ```
    Сервер автоматически начнёт синхронизацию с указанными пирами (peer_nodes) с заданным интервалом (sync_interval).

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


   ### Команды для управления репликацией

   В проекте добавлены следующие команды для управления репликацией:
   ```sh
       replication on — включить репликацию
       replication off — выключить репликацию
       replication status — получить статус репликации (включена/выключена, список пиров, время последней синхронизации)
       replication add-peer <addr> — добавить пир для репликации (например, replication add-peer 127.0.0.1:8081)
       replication remove-peer <addr> — удалить пир из списка репликации
   ```


## Резервное копирование

 Для создания и восстановления из бекапа используются команды futload (восстановление из бэкапа) и futunload (создание бэкапа).
 Вот примеры использования команд futload (восстановление из бэкапа) и futunload (создание бэкапа) в Futriix CLI:

futunload - Создание бэкапа

  ```sh

 futunload <путь_к_файлу_бэкапа>
```

Пример 1: Создать бэкап в текущей директории
```sh
futunload ./backups/snapshot_2024.fut

Вывод при успехе:
text

Backup created successfully at ./backups/snapshot_2024.fut
```

Пример 2: Создать бэкап с абсолютным путём

```sh
futunload /var/backups/futriix/db_export.fut
```

2. futload - Восстановление из бэкапа

Формат команды:
bash
```sh
futload <путь_к_файлу_бэкапа>
```

Пример 1: Восстановить из локального файла
bash
```sh
futload ./backups/snapshot_2024.fut

Вывод при успехе:
text

Backup restored successfully from ./backups/snapshot_2024.fut
```

Пример 2: Восстановить из системного пути
```sh
futload /mnt/backups/prod_db.fut
 
 ```

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


## HTTP API

Добавление данных:

  ```sh

curl -X POST http://localhost:8081/api/insert \
  -d '{"user_42": {"name":"John", "age":30}}'
```

Получение данных:

```sh
curl -X GET http://localhost:8081/api/get/user_42

{"name":"John","age":30}
```
```sh
Пакетное обновление:

curl -X POST http://localhost:8081/api/update \
  -d '{"user_42": {"age":31}, "product_5": {"price":99}}'
   
 ```
Пример Python-программы с использованием HTTP-API:

```sh
import requests
BASE_URL = "http://localhost:8081/api"
def set_value(key, value):
    requests.post(f"{BASE_URL}/insert", json={key: value})
def get_value(key):
    return requests.get(f"{BASE_URL}/get/{key}").json()

```

**Выключение сервера через CLI**

 Для того чтобы выключить сервер через CLI, используйте команду `shutdown` введя её в `clif`:
   
 ```sh
 futriix:~> halt
 Server shutdown initiated
  ```

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


## Lua-скрипты

> [!CAUTION]
> **Поддержка работы lua в настоящий момент эксперементальная и может вызвать аварийное завершение сервера!!!**

1. Интерактивный режим работы, (выполнение скрипта в клиенте `futriix-cli`):

```sh
  futriix:~> futexec
lua> return "Hello, " .. os.date("%Y-%m-%d")
```

2. Выполнение файлов скриптов (c помоью команды в клиенте `SysExec`):

    ```sh
    futriix:~> sysexec my_script

   ````

3. Доступ к данным из сервера Lua на примера lua-скрипта для чтение и записи данных из субд

Скрипты имеют доступ к специальному API:

```sh
-- read.lua 
-- Чтение данных
local value = futriix.get("my_key")

-- Запись данных
futriix.put("temp_key", {data = "test", ts = os.time()})

-- Пример сложной логики
for i = 1, 10 do
    futriix.put("counter/"..i, i*2)
end
```

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


## Проблемы

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

1. **Описание проблемы:** После запуска futriix, в лог-файле `futriix.log` дата указывается без указания текущего года:
   ```sh
     11:29:49 [INFO] Futriix Server started successfully
     11:29:49 [INFO] Listening on: 127.0.0.1:8080
   ```

**Решение:**
```sh
На данный момент это выявленный программный баг, нужно ждать выпуска новой версии. :-))
```

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

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

- [x] Реализовать поддержку хранимых процедур
- [x] Реализовать поддержку многопоточности
- [x] Реализовать неблокирующие чтение/запись
- [x] Реализовать мульти-мастер асинхронную репликацию через файл конфигурации
- [x] Реализовать логирование
- [x] Реализовать команды сервера для управления репликацией
- [x] Реализовать поддержку первичных индексов
- [x] Реализовать поддержку протокола MessagePack
- [x] Реализовать поддержку транзакций
- [x] Добавить механизм сторонних модулей на языке lua, расширяющих базовый функционал сервера
- [x] Добавить макет интеллектуального помощника FutBot
- [x] Реализовать проверку запуска сервера при запуске клиента (если сервер НЕ запущен клиент не запускается)
- [x] Реализовать поддержку HTTP-restfull API
- [x] Исправить ошибки записи журнала логов (в журнал лога кроме текущего времени добавить текущий год)
- [ ] Реализовать утилиту тестирования сервера на количество запросов на чтение/запись
- [ ] Реализовать поддержку алгоритма Raft
- [ ] Реализовать поддержку SQL
- [ ] Реализовать поддержку вторичных индексов
- [ ] Реализовать поддержку ACID-транзакций
- [ ] Реализовать полноценного интеллектуального помощника FutBot, задачами которого будут быстрый поиск ответов на вопросы, возникающие при эксплуатации субд Futrix.

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

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

<!-- CONTRIBUTING -->



<!-- 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>