From 3ab6b486ca043d237b89fe530cb10ca89b489344 Mon Sep 17 00:00:00 2001 From: Jose Bollo Date: Mon, 4 Nov 2019 12:02:03 +0100 Subject: Improvement of documentation Signed-off-by: Jose Bollo --- protocol.md | 243 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 protocol.md (limited to 'protocol.md') diff --git a/protocol.md b/protocol.md new file mode 100644 index 0000000..502595b --- /dev/null +++ b/protocol.md @@ -0,0 +1,243 @@ +The cynagora protocol +===================== + +Introduction +------------ + +### Notations: + + - c->s: from client to cynagora server + - s->c: from cynagora server to client + - CACHEID: a 32 bits positive integer + - ID: a string + - EXPIRE: if missing, means: can cache forever + if `-`, means: don't cache + if TIMESPEC (see below), means: valid until given RELATIVE time + - SEXPIRE: Same as EXPIRE but also allows TIMESPEC prefixed with '-', meaning + valid until given relative time and don't cache + +For TIMESPEC see notes. + +Messages +-------- + +### hello + +synopsis: + + c->s cynagora 1 + s->c done 1 CACHEID + +The client present itself with the version of the protocol it expects to +speak (today version 1 only). The server answer yes with the acknoledged +version it will use and the CACHEID that identify the cache (see note on +CACHEID) + +If hello is used, it must be the first message. If it is not used, the +protocol implicitely switch to the default version. + + +### invalidate cache + +synopsis: + + s->c clear CACHEID + +The server ask the client to clear its cache and to start the cache whose +identifier is CACHEID. + +This is the responsibility of the client to clear its cache. It is also a +decision of the client to implement or not a cache. If the client implements +a cache, it must clear that cache when it receives that message from the +server or otherwise its decisions would be wrong. + + +### test a permission + +synopsis: + + c->s test ID CLIENT SESSION USER PERMISSION + s->c (ack|yes|no) ID [EXPIRE] + +Check whether the permission is granted (yes) or not granted (no) +or undecidable without querying an agent (ack). + +This query ensure that the response is fast because agent are allowed to +delay requests before emitting the final status. But it doesn't ensure that +the answer is a final status. Receiving `ack` means that no final decision +can be decided. In that case the correct resolution is either to act as if +`no` were received or to ask for a check with not null probability that the +reply will take time. + + +### check a permission + +synopsis: + + c->s check ID CLIENT SESSION USER PERMISSION + s->c (yes|no) ID [EXPIRE] + +Check whether the permission is granted (yes) or not granted (no) and invoke +agent if needed. + +Agents are allowed to query user, remote server or any long time processing +that may delay a lot the reply. So don't forget when using check that the +reply might take time. + + +### enter critical (admin) + +synopsis: + + c->s enter + s->c done + +Start modifications (prior to set or drop). + + +### leave critical (admin) + +synopsis: + + c->s leave [commit|rollback] + s->c done|error ... + +Terminate modifications and commit it (commit) or cancel it (rollback). + + +### erase (admin) + +synopsis: + + c->s drop CLIENT SESSION USER PERMISSION + s->c done|error ... + +Drop the rule matching the given filter (see FILTER). + + +### set (admin) + +synopsis: + + c->s set CLIENT SESSION USER PERMISSION VALUE [SEXPIRE] + s->c done|error ... + +Create the rule as given. + + +### list permissions (admin): + +synopsis: + + c->s get CLIENT SESSION USER PERMISSION + s->c item CLIENT SESSION USER PERMISSION VALUE [SEXPIRE] + s->c ... + s->c done + +List the rules matching the given filter (see FILTER). + + +### logging set/get (admin) + +synopsis: + + c->s log [on|off] + s->c done (on|off) + +Tell to log or not the queries or query the current state. + +With an argument, it activates or deactivates logging. Without argument, +it does nothing. + +In all cases, returns the logging state afterward. + +Logging is a global feature. The protocol commands that the server sends or +receives are printed to the journal or not. + + +### register agent (agent) + +synopsis: + + c->s agent NAME + s->c done|error ... + +Register the agent of NAME (see AGENT-NAME). The name must be valid. The +name must not be already registered, it must be unique. + + +### ask agent (agent): + +synopsis: + + s->c ask ASKID NAME VALUE CLIENT SESSION USER PERMISSION + c->s reply ASKID (yes|no) [SEXPIRE] + +The server ask the agent of `NAME` to handle the request to the rule +CLIENT SESSION USER PERMISSION and the agent VALUE. + +The agent implementation must return its result with the given associated +ASKID. If the agent implementation has to check cynagora for replying to +an agent request, it must use sub-check requests. + + +### sub check (agent): + +synopsis: + + c->s sub ASKID ID CLIENT SESSION USER PERMISSION + s->c (yes|no) ID [EXPIRE] + +Make a check in the context of an agent resolution. Same as `check` but +in the context of the agent query ASKID. + + +Notes +----- + +### TIMESPEC + +The TIMESPEC describe a number of seconds in the futur RELATIVE TO NOW. + +It can be a simple decimal integer. I can also use letters to designate +year (letter `y`), week (letter `w`), day (letter `d`), hour (letter `h`), +minute (letter `m`), second (letter `s`). + +It can also be one of the predefined value: `*`, `forever` or `always`, all +meaning endless. + +Examples: + + - 15d 15 days + - 1h 1 hour + - 5m30s 5 minutes 30 seconds + + +### CACHEID + +The cacheid identify the current cache. It changes each time the database +changes. After a disconnection, clients can use HELLO to check whether their +version of cache is still valid. This is implemented by the default C library. + + +### FILTER + +The commands `drop` and `get` are taking rule's filters. A rule filter +is a rule that accept the special character `#` as a catch all match. + +For examples, the rule filter `# X # #` macthes the rules that have the +session `X` for any client, any user and any permission. + + +### AGENT-NAME + +Agent's name are valid if it only contains the following characters: + + - latin letters upper or lower case (distinguished): `a`..`z` or `A`..`Z` + - digits: `0`..`9` + - one of the characters `@`, `$`, `-`, `_` + +It can not be longer than 255 characters. + +The case count so the agent 'a' is not the agent 'A'. + -- cgit 1.2.3-korg