# UNIPI SOL: Relazione Progetto FSS
**studente:** Claudio Candelori
**matricola:** 549710
**corso:** A
**anno:** 2022
**repo:** https://github.com/OneClaudio/OneClaDrive

## 1. Struttura del codice:
1. **SHARED:**
* **comm.h:** Codici di operazioni condivise fra server e API
* **utils.h:** Codice di appoggio contenente funzioni di utilita' usate in tutte le componenti
* **errcheck.h:** Libreria contenente macros di error checking
2. **FSS:** File Storage Server
* **server.c:** Il core di tutto il progetto, contiene anche il codice dei thread worker
* **filestorage.c:** Struttura dati (linked list) che ospita i file in RAM
* **idlist.c:** Una struttura dati che contiene una coda/lista di identificatori di client, usata sia come coda di id pronti (da manager a workers) sia come lista di id che hanno aperto un file.
3. **API:**
* **api.c:** Unica interfaccia che l'FSS ha bisogno di esporre per funzionare. Il client sfrutta esclusivamente le funzioni visibili al suo interno per comunicare col server
4. **CLIENT:**
* **client.c:** Client che, come da specifica, puo' sfruttare i vari cmd line args per chiamare funzioni dell'API e quindi scambiare file con il server.
* **optqueue.c:** Ospita una coda di opzioni con i relativi argomenti (ancora raw, non parsed), che il client puo' prendere ed eseguire uno ad uno.

## 2. Comunicazione SERVER/API:

typedef struct {
	CmdCode code;
	int info;
	char filename[PATH_MAX];
	} Cmd;

typedef enum CmdCode{ IDLE, CREATE,	OPEN, CLOSE,
                      WRITE, APPEND,READ, READN,
                      LOCK, UNLOCK, REMOVE, QUIT } CmdCode;

#define	O_CREATE 0x1
#define O_LOCK	 0x2

Il modo con cui l'API (e quindi i client) comunica quale operazione deve essere eseguita al server e' tramite l'invio di un oggetto di tipo `Cmd`, per le operazioni piu' semplici contiene gia' al suo interno tutte le informazioni sufficienti per eseguirle:
* `CmdCode code`: Codice (sfruttando il tipo enum) che identifica l'operazione richiesta.
* `char filename[PATH_MAX]`: Pathname del file su cui si vuole operare. Richiesto da tutte le operazioni (tranne la `readNFiles()`).
* `int info`: Parametro di informazioni ausiliari usate solo da poche operazioni. E' interpretato in maniera diversa a seconda dell'operazione. Per la `openFile()` conterra' i flag opzionali `O_CREATE, O_LOCK`. Per la `readNFiles()` invece rappresentera' il numero di file da leggere.

In tutto il progetto ho deciso di imporre come limite superiore alla lunghezza dei file `PATH_MAX` che e' definita in `<linux/limits.h>`. Anche se non e' un vero e proprio limite imposto dal sistema operativo, usarla conferisce la flessibilita' di poter scambiare messaggi con il server di dimensione fissata (come appunto `Cmd`).

typedef enum Reply{ OK, ANOTHER, CACHE, NOTFOUND, EXISTS,
                    LOCKED, NOTOPEN, ALROPEN, NOTLOCKED,
                    ALRLOCKED, EMPTY, NOTEMPTY, TOOBIG, FATAL
                    } Reply;

Analogamente alla struttura precedente, `Reply` contiene invece tutti i codici che il server puo' inviare al client come risposta. Si tratta pero' solo di errori che riguardano la logica delle operazioni richieste. I possibili errori interni del server (es: errori delle malloc, errori di IO) sono tutti controllati ma sono principalmente errori gravi e distruttivi, ergo, rientrano tutti nel tag `FATAL` e non hanno dei codici dedicati.
* `OK`: indica che l'operazione richiesta e' stata eseguita con successo, oppure che si puo' procedere al prossimo step (es: invio di file).
* `ANOTHER`/`CACHE`: usati ogniqualvolta il server debba restituire dei file possibilmente in blocco. Ad esempio la `readNFiles()` comunica al server quanti file vuole leggere, ma non e' detto che siano tutti disponibili, oppure a seguito di una `writeFile()` l'algoritmo di cache potrebbe espellere piu' di un file per far posto al nuovo file da scrivere. In questi casi il server e il client entrano quindi in un loop e, fintanto che il client riceve come risposta uno di questi due codici, e' segno che il client debba continuare a ricevere file.
* `ALROPEN`/`ALRLOCKED`: Gli unici codici che non sono veri e propri errori e sollevano semplicemente una notifica che indica la ridondanza dell'operazione richiesta. Non sono quindi distruttivi e se ricevuti non segnalano al client un fallimento dell'operazione (restituiscono 0), ma semplicemente stampano un warning.
* `TUTTI GLI ALTRI`: Questi sono i veri e propri codici di errore, indicano che l'operazione richiesta non e' andata a buon fine e ne indicano il motivo, in genere una logica delle operazioni sbagliata. Per ognuno di questi una funzione di supporto nell'API (`errReply()`) stampa un messaggio di errore e **setta ERRNO** con un codice quanto piu' analogo possibile.

I vari codici delle operazioni sono riutilizzati anche all'interno del file di log, grazie a due funzioni che restituiscono la stringa corrispondente al codice enum.

## 3. ERROR CHECKING:
Trovando molto poco leggibile il paradigma di esecuzione di certe funzioni dentro agli `if` per controllarne il valore di ritorno con conseguente gestione dell'errore, ho scritto una mia personale libreria che sfrutta pesantemente le macro, fortemente ispirata e semplificata da quella presente nel manuale Advanced Unix Programming (Rochkind). A mio parere questo metodo migliora di molto la leggibilita' del codice e gli `if` possono cosi' tornare a fare solamente il proprio "lavoro".

Principalmente una macro (le piu' usate sono `ErrNULL()` e `ErrNEG1( )`) esegue e confronta il valore di ritorno con il codice di fallimento. Se questo e' il caso genera un messaggio di errore, usando sempre lo stesso formato, con tutte le informazioni necessarie per risalirvi, dopodiche' salta ad una sezione di **codice di cleanup**. Il codice di cleanup e' delimitato dalle macro `ErrCLEANUP` ... `ErrCLEAN`, la prima contiene il label a cui saltano tutte le varie macro, inoltre stampa un warning se la zona di cleanup viene raggiunta (per dimenticanza) dal flusso di controllo.
Inoltre usando lo standard `gnu99` e' possibile dichiarare piu' volte la stessa label in blocchi annidati. Senza di questo una label puo' essere usata solo una volta in ogni funzione separata.
Alcune altre macro usate sporadicamente sono `ErrFAIL` e `ErrSHHH` che vanno direttamente al codice di cleanup senza controlli, la prima stampa il messaggio di errore mentre la seconda fallisce silenziosamente.

`-D_GNU_SOURCE`: inoltre permette di avere disponibile la funzione `strdupa()` che e' una `strdup()` che viene deallocata automaticamente all'uscita dello scope.

Alcune funzioni di libreria molto usate o funzioni d logging frequenti/stampa errori hanno una macro che snellisce ulteriormente la lettura e che ingloba al suo interno tutto l'error checking necessario, in genere ha proprio il nome della funzione originale in all caps come ad esempio:

#define LOCK(l) ErrERRNO(  pthread_mutex_lock(l)   );

#define FWRITE( addr, size, n, id) ErrNEG1(  fwrite( addr, size, n, id)  );

## 4. SERVER:

### 4.1. Componenti usate:

struct IdList{
    IdNode* first;		//enqId()--> x-[ ]<-[ ]<-[ ]<-[ ]<-[ ] -->deqId()		
    IdNode* last;		//	        ^                   ^	
    pthread_mutex_t mutex;	//	     first		      last
	}

**`IdList`:** utilizza un pattern molto usato all'interno del progetto,una singly linked list permette inserimento e estrazione in O(1), ma ricerca solo in O(n). Viene utilizzata all'interno del server come una **coda** usando le funzioni `enqId()` e `deqId()`. Viene utilizzata nella seguente struttura `File` per contenere la lista di clienti che hanno il file aperto, tramite le operazioni `enqId()` e `findRmvId()` per aggiungere/rimuovere un id, `findId()` per sapere se un certo id e' nella lista.
Dovendo distinguere quindi fra varie liste, ognuna di queste funzioni prende come parametro anche la lista su cui dovra' andare ad operare.

struct File{
    char  name[PATH_MAX];
    void*  cont;
    size_t size;
    
    IdList*	openIds;
    int 	lockId;
    
    struct File* prev;
    }

struct Storage{
    File* first;
    File* last;
    
	pthread_rwlock_t lock;
	
	size_t numfiles;
	size_t capacity;
	}

**`File`/`Storage`:** Essendomi riuscito a concentrare solo sulla politica FIFO la scelta iniziale e' ricaduta inizialmente sempre su una lista, ed e' quindi piu' adatta all'inserimento di nuovi file e all'espulsione dettata dal cache algorithm (`addNewFile()` e `rmvLastFile()` ) che avvengono in tempo costante, mentre le opzioni che richiedono di operare su un file specifico richiedono tempo lineare: la `getFile()` restituisce un riferimento al file cercato sul quale il server puo' eseguire tutti i controlli e le operazioni necessarie, in piu' e' presente un'operazione (`removeThisFile()`) per la rimozione di un file specifico (ottenuto tramite la getFile). Queste sono le uniche funzioni necessarie al server per operare sullo storage ed, essendo poche e semplici, in futuro possono essere sostituite con strutture dati piu' performanti a seconda dei bisogni.

Essendo lo storage un'unica entita' in tutto il lato server, e' dichiarato globalmente nell'header `filestorage.h` con il nome molto creativo di `Storage storage` e tutte le funzioni e i worker thread operano implicitamente su di esso senza bisogno di doverlo ricevere o passare come parametro ogni volta.
Contiene al suo interno una read/write lock, oltre ai parametri di dimensione e n. file.
L'aggiornamento di questi parametri avviene implicitamente ogni volta che i file vengono aggiunti o rimossi dalle funzioni per operare sullo storage `addNewFile()`, `removeLastFile()`, `removeThisFile()`. Ad eccezione di operazioni che incrementano la dimensione dei file (`WRITE`/`APPEND`) che invece se hanno successo aggiornano sia la dimensione dei file che dello storage.

### 4.2. Manager thread:
Il pattern utilizzato per la realizzazione del server e' quello **Manager-Worker** con **Thread-pool**.
Il thread manager corrisponde al main del server.c.
Ha una fase di avvio che utilizza per installare correttamente i gestori dei segnali, leggere ed inizializzare le opzioni e i vari limiti del server dal file di config, aprire il file di log, aprire la socket, avviare i thread pool e inizializzare le strutture con cui comunichera' con essi.

Dopo la fase di startup il manager entra in un suo ciclo che non verra' mai bloccato se non dall'arrivo dei segnali indicati dalla specifica. Il main si blocca sulla `pselect()` che puo' stare in ascolto dei vari fd E dei segnali e bloccarli automaticamente durante l'esecuzione di una qualsiasi operazione.

Se la `pselect()` viene interrotta da un segnale restituisce 0, non entra quindi nel loop di gestioni delle connessioni e viene semplicemente eseguita la funzione handler corrispondente che cambia lo stato del server e annota sul log l'evento, il server ha una variabile globale `Status` che puo' assumere i valori: `ON`,`SOFT`, `OFF`. Il secondo viene settato da SIGHUP, l'ultimo da SIGINT e SIGQUIT.

Il ciclo principale e' ovviamente dotato di condizioni di guardia che escono dal loop quando richiesto:
Esce se `Status==OFF`, `Status==SOFT && activeCid==0`, inoltre non accetta piu' nuove connessioni se lo stato passa a `Status==SOFT`.

Il manager accetta nuove connessioni e le inserisce nel set di fd controllati (`all`).

Per la comunicazione da manager a workers e' stata utilizzata come gia' accennato la `IdList pending` che e' dichiarata globalmente e viene usata come coda concorrente tramite le funzioni `enqId()` e `deqId()`, che al loro interno acquisiscono una lock (specifica di ogni `IdList`) prima di poter estrarre o inserire un nuovo id. Il manager inserisce gli id pronti con un'operazione da seguire su questa coda, mentre i thread vi si bloccano in automatico ogni volta che e' vuota in attesa di un client per cui soddisfare una richiesta. Allo spegnimento del server vengono inseriti sulla coda dei codici `TERMINATE`, uno per ogni worker creato, che indicano al worker di uscire e terminare cosi' in maniera pulita.

Gli fd vengono rimossi dal set di fd controllati durante l'esecuzione, da parte di un worker, delle richieste del client corrispondente. Il worker esegue esclusivamente **una singola API call** dopodiche' restituisce l'id del client su una named pipe `done`, cosiche' il manager possa reinserirlo nella lista di id ascoltati. Un client che vuole terminare le richieste invia una notifica di disconnessione (un `Cmd` con codice `QUIT`) ed ogni worker dopo aver ricevuto questa intenzione inserisce un codice speciale `DISCONN` nella pipe `done`, serve al manager che decrementa di conseguenza il numero di connessioni attive `activeCid`.

### 4.3. Worker threads:
Ogni thread, prende un Client ID (`cid`), dopodiche legge da esso il comando che vuole eseguire leggendo `Cmd cmd`, e ottiene dallo storage il file corrspondente sul quale operare (il nome univoco e' in `cmd.filename` e se presente nello storage il file corrispondente viene assegnato ad una variabile `File* f`).
Dopo di che entra in un lungo switch case sul tipo di richiesta ricevuta (`cmd.code`), controlla che il cliente abbia tutte le carte in regola e, se e' il caso, esegue e completa la richiesta, in genere chiudendo con `REPLY(OK)` o con una reply contenente i motivi per cui l'operazione non puo' essere completata.
Se si presenta une errore distruttivo (es: esaurimento memoria malloc) il worker risponde al client con `REPLY(FATAL)`, e subito dopo manda un segnale `SIGINT` al processo stesso per cercare di far spegnere tutto il server nel modo piu' pulito possibile.

### 4.4. Logfile:
Il logging e' effettuato da una macro `LOG()` nel manager, e da una macro `LOGOPT( outcome, file, size )` che prende in automatico informazioni sul ClientID `cid`, sull'operazione in corso `cmd.code`, e stampa l'esito dell'operazione, e se una lettura/scrittura la dimensione in Byte inviati/ricevuti, e ovviamente su quale file.
Di seguito un modello di un possibile logfile:

MAIN: CREATED WORKER THREAD #3
MAIN: SERVER READY
MAIN: ACCEPTED NEW CLIENT 8
MAIN: ACCEPTED NEW CLIENT 9
WORK: CID=8   OPEN   OK         		./FILES/clearly.png
WORK: CID=8   LOCK   OK         		./FILES/clearly.png
WORK: CID=9   WRITE  CACHE     127863 B	./FILES/riccio-barbq.jpg
WORK: CID=9   WRITE  CACHE     4192 B	        ./FILES/clinteast.jpg
MAIN: SOFT QUIT SIGNAL RECEIVED -> NO NEW CONNECTIONS ALLOWED
WORK: CID=9   WRITE  CACHE     58806 B	./FILES/absolutelyp.jpeg
WORK: CID=9   WRITE  CACHE     212741 B	./FILES/river-rms.jpg
WORK: CID=9   WRITE  OK        995122 B	./FILES/sand.gif
WORK: CID=6   OPEN   EXISTS     		./FILES/clearly.png
WORK: CID=7   LOCK   NOTFOUND   		./FILES/river-rms.jpg
WORK: CID=8   WRITE  TOOBIG     		./FILES/clearly.png

## 5. API:
Le varie funzioni richieste dalla specifica sono state tutte implementate e fanno largo uso di alcune funzioni interne:
* `int firstCMDREPLY()`: Invia al server un elemento di tipo `Cmd` contenente un bundle di informazioni che come gia' spiegato indicano operazione da eseguire, su quale file e un int di informazioni speciali. Subito dopo legge una `Reply` dal server cosi' che puo' capire se puo' continuare o no. Questa funzione e' in genere il primo comando di ogni funzione dell'API.
* `int RECVfile( char* savedir)`: Riceve dal server un file (non si sa quale) quindi ne legge in ordine dimensione, contenuto e pathname. Se la cartella `savedir` e' specificata invoca la funzione successiva sul file appena ricevuto. Usata sia dalla funzionalita' `readNFiles()` sia dalle funzioni che potrebbero ricevere file espulsi dal cache alg. (`openFile()`,`writeFile()`,`appendToFile()`) tramite la funzione `CACHEretrieve()`.
* `int SAVEfile()`: Salva il file specificato nei parametri `cont`,`size`,`pathname` nella cartella specificata, se la cartella non esiste viene creata dalla `mkpath()` che crea tutto il path necessario. E' stato deciso di trattare queste cartelle di "salvataggio" come se fossero dei "cestini". I file vengono stoccati dentro la cartella specificata come parametro. L'univocita' dei file e' mantenuta perche' l'informazione sul loro path univoco salvando viene scritta sul nome dello stesso file salvato.

## 6. CLIENT:
Il client e' stato costruito cercando di aderire quanto piu' possibile alla specifica di progetto, che afferma che un'opzione debba potuta essere ripetuta piu' volte da un client. La scelta e' stata quindi quella di eseguire un parsing iniziale con la funzione `getOpt()`, e trovare tutte le opzioni iniziali (-h, -f, -p). Tutti gli altri comandi vengono inseriti in una coda `optQueue`, e eseguiti successivamente nell'ordine in cui appaiono sulla linea di comando.
Prima di iniziare ad eseguire le azioni elencate, ogni client invoca la `openConnection()` sulla socket specificata dall'opzione -f o su una di dafult, ed installa un handler per il segnale `SIGPIPE`.

I comandi della specifica sono stati interpretati nel seguente modo:
* **-h, -f, -p:** sono per configurare informazioni iniziali di tutta l'esecuzione del client.
* **-d, -D, -t:** sono per aggiornare informazioni che hanno la possibilita' di cambiare durante l'esecuzione del client. Ad esempio `./client -t 200 -w ./READ -t 500 -R` scrivera' tutti i file della cartella `./READ` a ritmo di uno ogni 200ms, il secondo -t cambia l'intervallo a 500ms e quindi il client continuera' a leggere i file dal server uno ogni 500ms.
* **-w, -W:** Non essendo presente in specifica un singolo comando per aprire/chiudere i file, ho deciso di adattarmi a questa indicazione. Le opzioni di scrittura invocano implicitamente una `openFile(..., O_CREATE | O_LOCK, ...)` dopodiche' scrivono il file con la `writeFile()` e successivamente chiudono il file con `closeFile()`, ognuna di queste API call avviene con il ritardo specificato da -t.
* **-r:** Allo stesso modo -r esegue una `OPEN`>`READ`>`CLOSE` ma stavolta la open avviene senza flag di creazione/lock.
* **-l, -u:** La -l esegue una `openFile()` e una `lockFile()` che puo' eventualmente bloccarsi in caso di file bloccato da altri client. La -u esegue una `unlockFile()` seguita da una `closeFile()`. Le lock sono indispensabili per eseguire le seguenti operazioni di append -a e rimozione -c, a differenza della -w che assume la lock implicitamente.
* **-a:** Opzione aggiunta per testare la funzionalita' di append. Necessita di una chiamata -l antecedente sullo stesso file per avere successo. Accetta 2 file, di cui il primo e' l'informazione da appendere e il secondo la destinazione.
* **-R:** Ho scelto di interpretare l'opzione -R come un grande dump di tutto lo storage, per ottenere i contenuti di tutti i file al suo interno (meno quelli locked da altri client). Quindi sia lato server che lato client la `readNFiles()` non richiede che i file vengano aperti precedentemente, ne invoca una `openFIle()`.

Tutte le opzioni vengono eseguite in uno switch case sulla lettera corrispondente all'opzione. Tutte le opzioni che accettano una lista di file separati, inoltre, hanno un ciclo interno allo switch case in cui viene fatto il parsing di ogni file con la funzione di libreria `strtok_r` e per ogni file eseguito il comando corrispondente.

## 7. MAKEFILE/TESTING:
Il progetto ha una struttura:
**SRC**: Contiene tutti i vari file sorgente divisi per ogni componente, e i file di oggetto creati in una sottocartella di ogni componente in modo che non ingombrino.
**BIN**: Contiene la cartella degli ASSET sui quali e' stato testato il progetto, e gli eseguibili e i file generati dall'esecuzione come socket e logfile.
**TEST**: Contiene gli script in bash e le diverse config richiesti dalla specifica.
**DOC**: Licenze e questa relazione.

Le varie cartelle sono dichiarate all'interno del makefile come variabili e quindi facilmente modificabili se si vuole cambiare la struttura delle folders.

Gli script dei test in bash vedono automaticamente il contenuto della cartella degli asset e lo assegnano ad un array che poi viene mischiato con il comando `shuf` in modo che ogni esecuzione risulti almeno parzialmente randomizzata. Questo approccio mi ha permesso di correggere varie dimenticanze che potrei non aver riconosciuto con dei test statici.
Ulteriori file di test possono essere aggiunti direttamente nella cartella FILES e verranno utilizzati dai client.
Sia server che client vengono lanciati in background con i vari timer indicati dalla specifica.

## 8. COMMENTI FINALI:
Avendo avuto problemi con le tempistiche, sono assenti alcune funzionalita' richieste dalla specifica. In particolare: sono assenti le informazioni di recap stampate dal server alla fine dell'esecuzione e il parser del logfile, anche se il logfile e' stato pensato per poter estrapolare semplicemente tutte le informazioni che si vuole.
Inoltre non ho avuto modo di testare il progetto sul sistema operativo fornito dal corso. Ad ogni modo lo sviluppo e' stato portato avanti su una macchina con Linux Mint XFCE che dovrebbe essere molto simile alla VM di XUbuntu che era stata fornita.
Il codice e' ampliamente commentato completamente in inglese, ma manca una specifica dettagliata di tutte le funzioni.