- 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
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.
--- /dev/null
+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.
+
+
+
- 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
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
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
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)
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)
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)
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)
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):
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):
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
### 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
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'.
+
Code Review / src / cynagora.git / commitdiff