# Lindux Dokumentacja końcowa
[TOC]
## Temat i treść zadania
Napisać wieloprocesowy system realizujący komunikację w języku komunikacyjnym Linda.
Do komunikacji użyć potoków nazwanych (FIFO). Komunikacja koordynowana przez centralny proces.
## Skład zespołu
* Damian Kolaska
* Jakub Kowalczyk
* Magdalena Majkowska
* Alicja Turowska
## Data przekazania 09.06.2021
## Interpretacja treści zadania
Celem projektu jest umożliwienie komunikacji międzyprocesowej przy użyciu interfejsu wzorowanego na języku komunikacyjnym Linda.
W ramach projektu powstanie biblioteka, której udogodnień będzie można użyć do stworzenia aplikacji serwera oraz klienta.
Biblioteka będzie umożliwiała klientowi, po nawiązaniu połączenia z serwerem, przesyłanie krotek, ich odbieranie oraz podglądania krotek zgodnych z podanym przez klienta wzorcem. Elementem krotki może być liczba całkowita, zmiennopozycyjna, lub napis. We wzorcu klient może ograniczyć krotki do ciągu podanych typów elementów, bądź ograniczyć dany element krotki do konkretnych wartości za pomocą operatorów porównania (=, <, >). Klient po zakończeniu korzystania z systemu komunikacji powinien zamknąć połączenie. System zostanie zrealizowany za pomocą potoków nazwanych z procesem centralnym.

Proces centralny będzie jednostką odpowiedzialną za przechowywanie krotek i udostępnianie powyższych funkcjonalności innym procesom (procesom klienckim), z którymi komunikacja będzie zapewniona przez zestaw potoków nazwanych stworzonych przez proces centralny do obsługi konkretnego klienta oraz potokom pełniącym rolę magistrali, służącym do nawiązania połączenia.

### Diagram architektury

## Opis funkcjonalny "black box"
System jest podzielony na dwie oddzielne aplikacje: serwera i klienta. Jako pierwszy zawsze uruchamiamy serwer. Następnie możemy uruchomić aplikację klienta. Aplikacja automatycznie wyśle żądanie połączenia do serwera i po chwili powinniśmy ujrzeć w konsoli znak zachęty. Klient posiada prosty interfejs terminalowy przez który możemy wprowadzać do systemu lub pobierać z niego krotki.

## Krótki opis funkcjonalny
### Sekwencja zdarzeń
#### Start systemu
1. Serwer zostaje uruchomiony.
2. Zostają utworzone dwa potoki, które będą pełniły rolę głównej magistrali.
#### Nawiązanie połączenia
1. Klient wysyła na głównej magistrali prośbę o otwarcie połączenia.
2. Serwer odbiera komunikat od klienta i tworzy zestaw potoków do komunikacji z danym klientem. W odpowiedzi wysyła nazwę zestawu potoków.
3. Serwer, na potrzeby obsługi klienta, tworzy nowy wątek, który od teraz będzie zajmował się komunikacją z danym klientem.

#### Wysłanie krotki
1. Klient wysyła krotkę.
2. Wątek serwera odbiera krotkę i sięga do bazy krotek.
3. W pierwszej kolejności przejrzana zostanie kolejka oczekujących na krotki. Jeżeli w trakcie iterowania kolejki trafimy na wątek, który wywołał operację Input, krotka nie jest dodawana do bazy tylko bezpośrednio przekazywana do wątku.
4. Po przejrzeniu kolejki oczekujących i upewnieniu się, że krotka o takich samych wartościach nie jest już przypadkiem obecna, dodajemy krotkę do bazy.
5. Aby zapewnić spójność, operacje na krotkach będą wykonywane w sekcji krytycznej. Synchronizacja zostanie zapewniona za pomocą mutexów.
#### Odbieranie krotki
1. Klient wysyła do serwera komunikat o chęci pobrania danej krotki
2. Na podstawie przekazanego w komunikacie wzorca krotki, serwer odszukuje odpowiadający mu zestaw danych. Jeżeli odczyt był operacją input, następuje zablokowanie sekcji krytycznej.
3. Jeżeli krotka została odnaleziona, potokiem zwracana jest jej zawartość.
3.1 W przeciwnym wypadku odblokowujemy sekcję krytyczną i czekamy na pojawienie się interesującej na krotki. Aby nie doprowadzić do zagłodzenia oczekujących procesów, zostanie zdefiniowana kolejka FIFO, która pilnować będzie tego, aby proces który wcześniej wysłały komunikat do serwera, miały większy priorytet.

## Opis implementacji
### Serwer
Serwer posiada główny wątek, który przy pomocy funkcji **poll** przegląda deskryptory potoków pełniących rolę głównej magistrali w oczekiwaniu na połączenie się nowego klienta. Po odebraniu wiadomości z prośbą o połączenie. Serwer tworzy nowy zestaw potoków o losowo generowanej nazwie, a następnie odsyła je wraz z wiadomością potwierdzającą udane nawiązanie połączenia do klienta. Na koniec tworzy nowy wątek, który od teraz będzie zajmował się komunikacją z tym klientem. Nowy wątek zwany przez nas wątkiem serwisowym odbiera kolejne operacje od klienta, wykonuje je i odsyła odpowiedzi do klienta.

### Klient
Klient na starcie wysyła do serwera komunikat z prośbą o połączenie. Następnie czeka na odpowiedź od serwera. Po otrzymaniu potwierdzenia nawiązania połączenia przechodzi do funkcji zajmującej się interakcją z użytkownikiem. Funkcja pobiera komendy od użytkownika, formuje z nich komunikaty, wysyła je do serwera, czeka na odpowiedź, a po otrzymaniu prezentuje wynik użytkownikowi.

### Struktura komunikatów przesyłanych w potoku i ich serializacja
Przykładowy komunikat

struct ServerConnectionResponse : public Message {
    ServerConnectionResponse() {}
    ServerConnectionResponse(bool connected, const std::string& fifo_write,
                             const std::string& fifo_read)
        : connected(connected), fifo_write(fifo_write), fifo_read(fifo_read) {}

    MsgType GetType() { return TYPE_SERVER_CONN_RESPONSE; }
    bool connected;
    std::string fifo_write;
    std::string fifo_read;
};

Wszystkie komunikaty dziedziczą po typie *Message* i mają zdefiniowaną metodę pozwalającą na określenie typu wiadomości.

struct Message {
    virtual MsgType GetType() = 0;
};

#### Serializacja
Komunikaty są serializowane pole po polu zaczynając od serializacji samego typu wiadomości. Łańcuchy znakowe są serializowane w ten sposób, że na samym początku umieszczamy ich długość. Deserializator rozpoczyna od wyszukania w strumieniu bajtów typu wiadomości, a potem wywołuje odpowiednią funkcję, która deserializuje kolejne pola.
### Problem odbierania danych
Przesyłając dane przez potok nie mamy gwarancji, że wysyłają wiadomości, druga strona odbierze je w takich samych porcjach. Z tego powodu zastosowaliśmy proste bufurowanie. Przed wysłaniem, a po serializacji wiadomości do strumienia bajtów, na koniec dodawany jest znak terminujący (w naszym przypadku $). Następnie przy odbiorze dane są wczytywane do momentu napotkania znaku terminującego i umieszczane w buforze. Nie jest to rozwiązanie idealne, ponieważ znak terminujący może przypadkowo znaleźć się w strumieniu bajtów czy to jako fragment łańcucha znakowego czy to jako losowy bajt. Takie rozwiązanie jest jednak wciąż lepsze niż całkowity brak oznaczania końca wiadomości.

### Utrzymywanie połączenia
Połączenie jest utrzymywane do momentu w którym klient wyśle wiadomość z prośbą o rozłączenie.
Serwer nie posiada rejestru połączeń.
I
Połączenie może być zamknięte w dwóch przypadkach:
* Jeśli w trakcie trwania połączenia, klient nie wysłał żadnego pakietu przez X sekund, gdzie X jest stałą podawaną jako argument wywołania serwera, zamykamy połączenie.
* Jeśli klient wysłał komunikat ConnectionMessage z flagą connect ustawioną na false.

## Struktury danych
### Przechowywania krotek przez serwer
Krotki będą przechowywane w kontenerze asocjacyjnym (np. std::unordered_map) gdzie kluczem będzie rozmiar krotki. Pozwala to na szybką identyfikacje krotek o danej długości.

std::unordered_map<int, std::vector<std::vector<TupleElem>>> records;

### Kolejka wątków oczekujących
Wątki którch operacja Read lub Input nie powiedzie się z powodu braku pasującej krotki w pierwszej kolejności tworzą pomocniczą strukturę AwaitingThread. Posiada ona następujące pola:

struct AwaitingThread{
    std::vector<Pattern> tuple_pattern;
    std::mutex mutex;
    bool isInput;
    std::vector<TupleElem> passed_tuple;
}

Następnie zawieszają się na przechowywanym przez nią mutex'ie.
Sama kolejka wątków oczekujących jest zaś vectorem owych struktur:

std::vector<AwaitingThread*> waiting_threads_queue;

Informacje jakie zawiera *AwaitingThread* pozwalają podczas iteracji kolejki obudzić dany wątek oraz przekazać mu krotkę na która czekał. Przeglądanie kolejki oczekujących kończy się w momencie przejrzenia całej lub trafienia na strukturę której zmienna *isInput* jest równa *True*.

### Reprezentacja krotek i wzorców krotek
Krotki będą reprezentowane jako tablica (std::vector) obiektów TupleElem.

std::vector<TupleElem> tuple = {1, 2.5, "hello"};

Obiekty TupleElem to po prostu std::variant

using TupleElem = std::variant<int, double, std::string>;

Szablony krotek będą reprezentowane przez tablicę (std::vector) obiektów pochodnych klasy Pattern (String, Float, Integer)

std::vector<Pattern> pattern = {Int("*"), Float(">2.5"), String("hello")};

## Synchronizacja
Ze względu na specyfikację kolejek FIFO nie mamy mozliwości sprawdzenia od jakiego procesu nadeszła wiadomość, dlatego dostęp do magistrali serwera jest chroniony nazwanym semaforem. Naraz może się komunikować z serwerem na magistrali tylko jeden proces.

Zaimplementowane sekcje krytyczne zapobiegają jednoczesnej modyfikacji bufora krotek oraz kolejki oczekujących przez więcej jak jeden wątek. Dostępu do nich strzegą w bazie danych dwa mutexy:
* Pierwszy odpowiedzialny za operacje na mapie krotek,
* Drugi odpowiedzialny za operacje na kolejce oczekujących.

## Zobrazowanie pełnej sekwencji zdarzeń


## Moduły i komunikacja między nimi
### Struktura katalogów
* bin - tutaj trafiają pliki wykonywalne
* build - tutaj budujemy nasz projekt
* lib - biblioteki statyczne
* test - testy
* apps - aplikacje testowe
* integration - testy integracyjne w bashu
* unit - testy jednostkowe
* include - pliki nagłówkowe
* src - pliki źródłowe
### Moduły
* server - moduł serwera
* client - moduł klienta
* common - ogólne funkcje pomocnicze i często używane pliki nagłówkowe
* linda_common - funkcje pomocnicze związane ściśle z pracą systemu, które są używane zarówno w module klienta jak i serwera
* tuple - klasy związane z obsługą krotek i wzorców krotek
* serializer - funkcje służące do serializacji komunikatów
* deserializer - funkcje służących do deserializacji komunikatów
* parser - parser komend podawanych na wejściu do programu
* message_buffer - synchronizowany bufor na komunikaty
* service_thread - definicja wątku serwisowego
* server_db - synchronizowany kontener na krotki


### Przebieg komunikacji

## Postać plików konfiguracyjnych i logów
Aplikacje serwera i klienta uruchamiane są bez użycia plików konfiguracyjnych ponieważ, w trakcie interpretowania tematu projektu nie zauważyliśmy ich potrzeby.
Do logowania używamy biblioteki LOGURU, która pozwala na łatwy zapis do pliku/do terminala oraz udostępnia przyjemny, aczkolwiek elastyczny interfejs programisty. Tworzone przez nią logi posiadają w odróżnieniu od innych bibliotek również oznaczenie, który wątek dopisał coś do pliku oraz linię kodu, z której zostało wywołane utworzenie logu.
Serwer zapisuje swoje logi na standardowe wyjście oraz do pliku. Klient jedynie do pliku.

### Format logów

## Opis terminalowego interfejsu klienta
Dostępne polecenia to help, input, output, read oraz exit. Polecenie help wyświetla krótką pomoc. Poleceniem exit zamykamy sesję klienta. Polecenia input, output i read odpowiadają poleceniom zdefiniowanym dla języka Linda. Po wykonaniu jednego z tych poleceń w odpowiedzi powinniśmy dostać szukaną krotkę lub informację o błędzie. W przypadku w którym szukanej krotki nie ma aktualnie na serwerze, klient zawiesza się do momentu uzyskania pożądanej krotki.


## Testy
### Testy jednostkowe
#### Parsowanie komend
Testy sprawdzające poprawne parsowanie pojedynczych komend z krotkami o różnych długościach i różnych typach danych.

#### Wyniki testów jednostkowych

Przed integracją poszczególnych części projektu w całość, testowaliśmy oddzielne poszczególne z jego części. Dzięki temu już na poziomie pierwszych prac modułów wykrywaliśmy błędy implementacyjne, co oszczędziło nam dużo pracy podczas integracji programu. Najbardziej wymagające okazało się testowanie krotek i ich dopasowywania do wzorca, ale dzięki rozbiciu każdego przypadku na oddzielny test jednostkowy wykryliśmy (mamy nadzieję) wszystkie nieprawidłowości.

#### Serializacja
Dla każdego typu komunikatu definiujemy przykładowy komunikat, serializujemy go, następnie deserializujemy. Oczekujemy, że otrzymamy z powrotem pierwotny komunikat.
#### Wzorce krotek
Testy sprawdzające czy wzorce poprawnie dopasowują się do krotek.
### Testy integracyjne
Testy postaci

echo "----------------TEST--------------------"
echo "DESCRIPTION"
bin/server > /dev/null 2>&1 &
sleep 1
bin/client test.log < test/integration/example/input.txt

Przykładowe scenariusze:
* klient od razu się rozłącza
* klient dodaje krotkę, a potem ją odczytuje
* jeden klient dodaje krotkę, a dwóch innych klientów próbuje wykonać operację *input*
* kilku klientów próbuje się połączyć, od razu się rozłącza

#### Wyniki testów integracyjnych

Podczas testów integracyjnych zauważyliśmy problem serwera z usuwaniem krotek. Kod serwera było bardzo trudno przetestować jednostkowo bez gotowego klienta, dlatego sprawdzaliśmy poprawność jego implementacji na poziomie integracji. Problem polegał na usuwaniu zmiennej lokalnej, która była podawana przez kopię, a nie przez referencję, zatem obiekt źródłowy nie ulegał zmianie.

Reszta testów integracyjnych przebiegła bez większych problemów.

### Test akceptacyjny
Uruchomienie serwera, a następnie w oddzielnych sesjach terminala kilku klientów.
Holistyczna ocena działania systemu. Zwracamy uwagę czy system nie zakleszcza się,
czy serwer rzeczywiście zwraca krotki, których oczekiwaliśmy, itd.

## Stos technologiczny
### Język
Rozwiązanie planujemy zaimplementować w języku C++17.
### Biblioteki
* Loguru https://github.com/emilk/loguru - logger
* Google Test - biblioteka do testowania
* pthread - implementacja wielowątkowości
* fmt - wygodne formatowanie tekstu
### Środowisko developerskie
* CLion https://www.jetbrains.com/clion/ - IDE
* Visual Studio Code - edytor kodu
* gdb z dodatkiem https://github.com/pwndbg/pwndbg - debugger
* ClangFormat - formater kodu
* git - system kontroli wersji