Syncrepl client API

[Pierangelo Masarati <ando@sys-net.it>]

I've implemented a client API for the LDAP Content Synchronization 
operation (RFC4533) which basically provides a clean and simple 
interface to using the operation to sync client's data based on the 
status of the producer.  This is not only intended to provide 
replication capabilities, but also to implement client-side "persistent 
search"-like feature based on stock slapd (>= 2.3), without the need to 
revamp the persistent search IDs and code yet another overlay.

The API essentially consists in a data structure that contains data 
required to initiate/re-initiate the search operation, to keep track of 
the current state, plus a set of handlers that will be called based on 
the event that occurs: when a search entry, a search reference, an 
(already parsed) RFC4533 intermediate response or a search result done 
message are received, respectively.  This frees the client from knowing 
any of the details of RFC4533, except for a loose knowledge of the type 
of events that can occur.

Its usage is quite simple: set up the structure, including an already 
initialized connection handler, call ldap_sync_init() specifying the 
mode (refreshOnly, not implemented yet, or refreshAndPersist).  When 
using refreshOnly, that should be all; call ldap_sync_init repeatedly to 
refresh.  When using refreshAndPersist, repeated calls to 
ldap_sync_poll(), with different timeout policies, are required to 
inquire for further responses; the provider or the consumer could decide 
to restart (or connection to the producer could be lost for some reason; 
in that case, simply call ldap_sync_init() again.  Details about setting 
up the connection with appropriate data protection and authentication is 
left to the client, as it's out of the scope of syncrepl.

I would like to add this to libldap, as the customer that requested its 
implementation agreed in open sourcing it.  I'll post an ITS about this 
soon.  In the meanwhile, I'd like to hear general comments about the 
overall design.

One relevant point is that it strictly implements RFC4533, so delta 
syncrepl has not been even considered, as there's no specs for that.  
Initially, I thought a good place to test and use this API would have 
been to replace the bundled syncrepl consumer code in slapd, but the 
absence of delta syncrepl makes this option non feasible.  This is a 
pity, because having it there would have meant lots of bug tracking and 
support from the community of syncrepl users.

Nonetheless, apart from my very limited knowledge of delta syncrepl 
implementation details, I don't think adding it to this public API would 
be a good idea, because it seems to imply a bit too much knowledge about 
its implementation details, like the contents of the sync cookie, and 
very precise and specific details about the implementation of the 
changelog database.  Either those details are coded in a document like 
RFC4533 (and freeze), or I would leave that optimization to slapd's 
internals.

p.



Ing. Pierangelo Masarati
OpenLDAP Core Team

SysNet s.n.c.
Via Dossi, 8 - 27100 Pavia - ITALIA
http://www.sys-net.it
------------------------------------------
Office:   +39.02.23998309
Mobile:   +39.333.4963172
Email:    pierangelo.masarati@sys-net.it
------------------------------------------