Commit 4adae0ca authored by Giacomo Strangolino's avatar Giacomo Strangolino
Browse files

documentation

parent 4b60769e
......@@ -37,6 +37,14 @@ The supervision and failover relies on the contributions of
4. *ca-proxies* do not store any state in memory, so that they can be restarted at any time without losing information, and failures have limited consequences, ideally compromising only the operation contextual to the failure.
## Database
Each database table is discussed in the documentation of the project that (mainly) accesses it in *write* mode.
For example, the *register* table is principally managed by the [caserver-proxy](https://gitlab.elettra.eu/puma/server/caserver-proxy)
and is described in its *README.md* project file [here](https://gitlab.elettra.eu/puma/server/caserver-proxy#database),
while the *activity* table is illustrated in this document [here](activity-table).
## ca-proxy tasks
The [ca-proxy](https://gitlab.elettra.eu/puma/server/caserver-proxy) receives requests from clients.
......@@ -154,7 +162,114 @@ more required.
## <a href="casup-db-tables"/>Database tables
### <a href="activity-table"/> running activities and recovery-related tables
#### 1. The activity table
The *activity* table is written by the ca-supervisor.
Every *subscribe* and *unsubscribe* (methods * "s", "S" and "u" *) message received from the clients by the
[caserver-proxy](https://gitlab.elettra.eu/puma/server/caserver-proxy) is forwarded to the *ca-supervisor*
in order to be respectively added or removed from the *activity* table.
The *activity* table is a *snapshot* of the *sources* being monitored at a given time, showing
which [caserver-proxy](https://gitlab.elettra.eu/puma/server/caserver-proxy) has registered them,
which client is monitoring them and on what *[nchan] channel*.
```
CREATE TABLE activity (
srv_id integer NOT NULL,
cli_id integer NOT NULL,
"source" varchar(512) NOT NULL,
chan varchar (1024) NOT NULL
);
```
operations on the *activity* table shall allow multiple contemporary running instances of the *ca-supervisor*,
as discussed in the ensuing *note*.
##### <a href="activity-table-note"/>Note
**Scenario**: three services, A, B and C. One *or more* supervisors.
If service A is monitoring *src1* on *ch1* and service B is assigned *src1* on *ch1* as well,
then *ca-supervisor* shall *update the activity table* rather than insert a new row, setting service B
as *srv_id* of *src1* and *ch1*
As a result,
- if service A goes down, there is no need to take care of (*src1, ch1*) in the failover operation
- if service B goes down, the failover operation will reassign (*src1, ch1*) to another available service (let's say either A or C),
and *ca-supervisor* will again update the *cli_id* where *source* and *chan* are (*src1, ch1*).
When a *recovery operation* is undertaken, the activities associated to a failing service shall be *moved* from the
*activity* to the *recover_activities* table. This avoids that another *supervisor* possibly inititates the same
operation at the same time. Contextually, activity information is temporarily moved to the
*recover_activities* table, where the operation data is saved alongside other accessory information stored within
*recover_operations*.
In case a recover operation *fails* (f.e. no other services available to take over stray sources), the involved
set of sources shall be moved again into the *activity* table, so that the operation can be retried later.
The important point here is that, in order to avoid concurrent operations by multiple *ca-supervisor* services,
the activities object of recovery must be removed from the *activity* table beforehand.
A final *recovery* table defined as follows:
#### 2. The register, service, clients and srvconf* tables
The *register, service, clients and srvconf* tables are discussed in the
[caserver-supervisor-plugin](https://gitlab.elettra.eu/puma/server/caserver-supervisor-plugin#database)
dedicated database section, since they are *modified* by the plugin.
#### 3. The recover_activities, recover_operations and recovery tables
The schema of the tables involved in the recovery operations are as follows:
```
CREATE TABLE "recovery" (
id SERIAL PRIMARY KEY,
srv_id integer NOT NULL,
started timestamp NOT NULL,
supervisor_id integer NOT NULL REFERENCES supervisor (id)
);
```
```
CREATE TABLE recover_activities (
operation_id INTEGER NOT NULL,
"source" varchar(2048) NOT NULL,
"chan" varchar(2048) DEFAULT NULL,
"cli_id" integer NOT NULL,
from_srv_conf INTEGER NOT NULL REFERENCES srvconf (conf_id),
to_srv_conf INTEGER DEFAULT NULL REFERENCES srvconf (conf_id)
);
```
```
CREATE TABLE recover_operations (
id SERIAL PRIMARY KEY,
supervisor_id INTEGER NOT NULL REFERENCES supervisor (id),
started timestamp NOT NULL,
complete timestamp,
success boolean
);
```
A *recovery* row records the start date and time of a recovery and links the *supervisor* in
charge of the operation to the service (with *srv_id*) that is failing.
At the time of writing, the current version of the *SQL* schema betrays redundancies
that shall be solved in a future version.
##### Note
None of the tables hitherto described shall be intended as historical. It is not guaranteed that
data is preserved after a recover operation, be it successful or not.
#### History tables
History tables are foreseen by the [database creation script](https://gitlab.elettra.eu/puma/server/caserver-proxy/-/blob/master/cadb-create.sql)
though currently the implementation does not access them.
## Command line
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment