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
  

### 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).


### 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.


### 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.


### 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.


### 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.


### register agent (agent)

synopsis:

	c->s agent NAME
	s->c done|error ...

Register the agent of NAME


### 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])

Receive an agent resolution request.


### 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.


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`).

Examples:

	- 15d


### 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.