Added server doc

doc/server.md

@@ -0,0 +1,57 @@
+# Server - developer documentation
+
+## File tree
+
+```
+./graphs
+    /setup_info_examples/       <-- Contains some examples out of the nicos/se_main measurement, field setup_info (these examples are not full setup_info value, they correspond to the value "content" in the _extract_variables method in the file influxdb.py)
+chart_config.py                 <-- Contains the ChartConfig class that represent a chart configuration (chart section out of generic.ini or <instrument>.ini)
+circularlog.py                  <-- Allows to log messages to some log files, with a maximum length of 80 messages
+colors.py                       <-- Allows color assignement to the available variables taken from InfluxDB
+influxdb.py                     <-- Contains all InfluxDB related code
+influxgraph.py                  <-- Implements the different routes when InfluxDB is used for the history
+seagraph.py                     <-- Implements some classes and functions used in the SeaGraph class
+seaweb.py                       <-- Main file (see seaweb.py section)
+tcp_lineserver.py               <-- Holds the necessary code for the communication (TCP) the for right part
+```
+
+## seaweb.py
+
+This file is the main one for the server.
+
+### Serving the application
+
+The Python module gevent is used to serve the different routes.
+
+Routes are managed with the Flask Python module. All routes are indicated with `@app.route` and refer to one function. Multiple routes can refer to the same Python function, as it is the case for the API and some files. The routes serve :
+- Files, as response to an URI or any files refered in some HTML code, or for the /export route : all functions that return `general_file` or `send_file`
+- API functions (called on clients) : the `reply` function that returns `application/json` content
+- Other : 
+    - the `/update` route which is assigned to a generator for the SSE connection
+    - the `/circular` route which logs the buffered messages and return the string "log"
+    - the `/clients` route which returns HTML with information about connected clients
+
+### Instrument
+
+When the the server is started, a global variable `instrument` is assigned in the `if __name__ == "__main__"` condition, holding an `Instrument` instance (derived depending on the type of instrument) which contains a list of the corresponding client types that are connected to the server. The derived `Instrument` classes need to override the method `newClient` in order to specify which type of client needs to be added when a new client is connecting. These derived classes can implement other methods that might be required when a client needs special information about the current instrument.
+
+The possible instrument types are the following :
+- `sea` (OBSOLETE) : creates an instance of `SeaInstrument`, which registers `SeaClient`. This uses SEA for both history and control.
+- `influxsea` : creates an instance of `SeaInfluxInstrument`, which registers `SeaInfluxClient`. This uses SEA for the control and Influx for the history.
+- `influx` : creates an instance of `InfluxInstrument`, which registers `InfluxClient`. This uses Influx for the history, and does not have control part.
+- `dummy` (NOT TESTED IN RECENT DEVELOPMENTS, PROBABLY OBSOLETE) : creates an instance of `DummyInstrument`, which registers `DummyClient`. This uses SEA for the history, and does not have control part.
+- `secop` (NOT TESTED IN RECENT DEVELOPMENTS) : creates an instance of `SecopInstrument`, which registers `SecopClient`. This uses directly TCP to communicate for the control part.
+
+The previously indicated behavior for the instruments are defined in the corresponding client class.
+
+In any cases, the server needs an instrument name in order to run, which is given by the key `instrument` in the arguments passed to run this file.
+
+### Clients
+
+A client is a class representing a client connection to the server. It also implements some methods that are called in response to client requests.
+
+As explained before, the instrument is responsible for creating and keeping track of connected clients in memory. In order for a client to connect, it first requests for the /update route (which will stay open), that creates an instance of the right client type (depending on the implementation of `newClient`) on the instrument, which assigns it an id. This is intended for the SSE connection, but also help to find the right client instance with which the server needs to call the methods. Then, each time a client makes a request, it will have to send its previously given id.
+
+As explained, each client implements some methods that will be called to client requests. These methods are identified by their name which have the format : `w_<route>`. All these methods return Python dictionnaries that can be converted to JSON response, except for the `w_export` method that returns bytes. These methods can be found directly in the definition of the client, or by inheritance from `SeaGraph`, `SeaParams`, `InfluxGraph` and/or `InfluxParams`. These four last classes were made to be able to factorize some code between the classes `SeaClient`, `SeaInfluxClient` and `InfluxClient`.
+
+Each client defines a `poll` function that allows the loop in the `generator` function to get the messages from it.