Improvement of documentation

Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>

3 files changed, 164 insertions, 15 deletions

diff --git a/README.md b/README.md
index 56959a9..e28eaaf 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,17 @@ value matches the string of the rule. That match is:
   - case insensitive for PERMISSION
 
 The string RESULT has basically one of the two values `yes` or `no`. It can
-also be an agent item that will imply a request to an existing agent.
+also be an agent item that will imply a request to an existing agent (see
+file agent.md for details on agents).
+
+When more than one rule match the query, only one is selected to apply using
+the following rules:
+
+  1. the rules that matched with the less STAR as possible are selected (it
+     means that selected rules must matche more precisely the request)
+  2. then from the rules selected above the rule that matches more exactly
+     the keys in the following order of priority: session, user, client,
+     permission
 
 Cynagora implements handles differently the rules targeting any sessions
 and the rules targeting specific sessions. The rules that have SESSION equals
@@ -60,14 +70,17 @@ of the rule in epoch (number of seconds since 1 January 1970). The special
 value 0 means no expiration, permanent rule. The negative values are used
 to avoid caching, their expiration value is given by the formula `-(1 + x)`.
 
+Cynagora allows tiers programs to add features through the agent mechanism.
+The file `agent.md` explains it more in detail.
+
 ## API Overview
 
 CYNAGORA comes with 2 APIs:
 
  - a protocol API that can be easily implemented in most languages
-   (see src/cynagora-protocol.txt)
+   (see `protocol.md`)
 
- - a client C library (see src/cynagora.h)
+ - a client C library (see `src/cynagora.h`)
 
 It also provide optionally for compatibility a subset of the C client libraries.
 
diff --git a/agent.md b/agent.md
new file mode 100644
index 0000000..4e19d45
--- /dev/null
+++ b/agent.md
@@ -0,0 +1,77 @@
+Agent of cynagora
+=================
+
+Cynagora provide a mechanism called agent that allows to add logic of
+autorization to cynagora. It can be used for example to query a user
+to autorize or not a permission ponctually.
+
+Cynagora server implements a predefined agent named the `at` agent that
+implements a simple redirection of a query.
+
+General principle
+-----------------
+
+Rules of the database have a RESULT. That result is either `yes`, `no` or
+an agent query. An agent query is of the form:
+
+	NAME:VALUE
+
+where NAME is the name of the agent, VALUE is a value attached to the rule
+and passed to the agent when querying it.
+
+The colon between the NAME and the VALUE is mandatory.
+
+The agent is queried to give a result with the following values:
+
+	VALUE CLIENT SESSION USER PERMISSION
+
+Example of the agent AT
+-----------------------
+
+The file `cynagora.initial` that provides a default initialisation file
+has the following lines:
+
+	*  *  @ADMIN  *  yes                forever
+	*  *  0       *  @:%c:%s:@ADMIN:%p  forever
+
+The first line defines a special user `@ADMIN` that always has the permission.
+The special user can be seen as a group: the admin group. Remember that strings
+of the database are conventionnal, that is that the meaning of the USER part
+is conventionnal. A common convention is to use the decimal representation of
+the UID of the unix account to check. That convention is used on the second
+line. That second line defines that the user root (UID 0) is in the group
+admin. To achieve that it uses the agent-AT mecanism.
+
+So if no other rule was selected for the user `0` then cynagora find at least
+the rule that requires to query the predefined agent `@` (AT) with the value
+`%c:%s:@ADMIN:%p`.
+
+The agent is asked with the following values:
+
+  - `%c:%s:@ADMIN:%p`  the value
+  - `CLIENT`, `SESSION`, `USER` and `PERMISSION`, the values of original request
+
+The AT-agent use the value `%c:%s:@ADMIN:%p` to compose a check query.
+it interpret the value as a colon separated rule query of cynagora, in the
+order: client, session, user, permission. Then it replaces any occurency of:
+
+  - `%c` with value of `CLIENT` of original request
+  - `%s` with value of `SESSION` of original request
+  - `%u` with value of `USER` of original request
+  - `%p` with value of `PERMISSION` of original request
+  - `%%` with `%`
+  - `%:` with `:`
+
+So for the given value, the result at the end is the result of querying
+cynagora for the result of:
+
+  - client: %c that is substituted by CLIENT
+  - session: %s that is substituted by SESSION
+  - user: @ADMIN
+  - permission: %p that is substituted by PERMISSION
+
+The query to cynagora with CLIENT SESSION @ADMIN PERMMISSION must be done using
+sub-query of agents.
+
+
+
diff --git a/src/cynagora-protocol.txt b/protocol.md
index ea3c1c2..502595b 100644
--- a/src/cynagora-protocol.txt
+++ b/protocol.md
@@ -11,8 +11,8 @@ Introduction
  - 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
+            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
 
@@ -44,8 +44,13 @@ synopsis:
 	s->c clear CACHEID
 
 The server ask the client to clear its cache and to start the cache whose
-identifier is CACHEID
-  
+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
 
@@ -57,6 +62,13 @@ synopsis:
 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
 
@@ -68,6 +80,10 @@ synopsis:
 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)
 
@@ -96,7 +112,7 @@ synopsis:
 	c->s drop CLIENT SESSION USER PERMISSION
 	s->c done|error ...
 
-Drop the rule matching the given filter.
+Drop the rule matching the given filter (see FILTER).
 
 
 ### set (admin)
@@ -118,7 +134,7 @@ synopsis:
 	s->c ...
 	s->c done
 
-List the rules matching the given filter.
+List the rules matching the given filter (see FILTER).
 
 
 ### logging set/get (admin)
@@ -130,6 +146,14 @@ synopsis:
 
 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)
 
@@ -138,7 +162,8 @@ synopsis:
 	c->s agent NAME
 	s->c done|error ...
 
-Register the agent of NAME
+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):
@@ -146,9 +171,14 @@ Register the agent of NAME
 synopsis:
 
 	s->c ask ASKID NAME VALUE CLIENT SESSION USER PERMISSION
-	c->s reply ASKID ([yes|no] [always|session|one-time|EXPIRE])
+	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.
 
-Receive an agent resolution request.
+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):
@@ -158,7 +188,8 @@ 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.
+Make a check in the context of an agent resolution. Same as `check` but
+in the context of the agent query ASKID.
 
 
 Notes
@@ -166,14 +197,20 @@ Notes
 
 ### TIMESPEC
 
-The TIMESPEC describe a number of seconds in the futur relative to now.
+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
+  - 15d    15 days
+  - 1h     1 hour
+  - 5m30s  5 minutes 30 seconds
 
 
 ### CACHEID
@@ -182,3 +219,25 @@ 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'.
+