-- Diaspora* user directory ----------------

TODO: update this section
This is an attempt to build a decentralised directory of diaspora* users.
As this problem has a lot in common with the problem of having a
decentralized PGP public key directory, which is already solved by the
SKS key server, it looks like a good idea to take the sks key server and
transform it into a diaspora user directory server.

This is to become a first proof of concept.

These are the python scripts:
   * partners.py: manages the synchronization partners list
   * test.py: Will test the synchronization automatically
   * testing/add_entry.py: adds a database entry for manual testing
   * sduds.py: This is the main program. It waits for other servers to
               connect. If you pass it a host and a port, however, it
               will connect to another server and synchronize with it,
               using the SKS reconciliation algorithm.

They make use of the following modules:
   * hashtrie.py: Used to start the trieserver executable.
   * entries.py: database access functionality
   * lib.py: some custom sqlalchemy types

Executables:
   * ./trieserver: This is the interface between the synchronization
                   algorithm of the SKS key server and python. The
                   python scripts make use of this executable, but
                   you never need to execute it manually.

-- Requirements for Ubuntu -----------

# apt-get install ocaml libdb-dev zlib1g-dev
# apt-get install python-paramiko python-sqlalchemy
# apt-get install python-setuptools && easy_install python-webfinger

-- Building --------------------------

$ cd trie_manager
$ cp Makefile.local.unused Makefile.local
$ make dep
$ make all

(tested with Ubuntu 10.04 - Lucid Lynx, and 11.10 - Oneiric Ocelot)

This will result in the 'trie_manager/manager' executable to be created.

-- Building the docs -----------------

Install sphinx documentation generator:

# apt-get install python-sphinx

For UML diagrams:

# apt-get install python-setuptools
# easy_install sphinxcontrib-plantuml

Download plantuml.jar from http://plantuml.sourceforge.net/download.html,
create wrapper script plantuml as described at http://pypi.python.org/pypi/sphinxcontrib-plantuml.

Build documentation:

$ cd doc
$ make html

-- Running the tests -----------------

Run all tests:

$ ./test.py

Run one test module:

$ python tests/partners.py
(`cd tests && python partners.py` will not work because the the current
 working directory must contain the necessary modules)

Run one test case:

$ python -m unittest tests.partners.ControlSampleCache

Run an indiviual test:

$ python -m unittest tests.partners.ControlSampleCache.test_failed

-- Trying it out manually ------------

TODO: update this section
Make two copies, compile each.

For one copy, do:

$ ./partners.py -e sduds2 "http://localhost:20020/" 1.0 sduds1
 ... type passwords ...
        (Adds the second instance of the program, which will
         run on port 20002, as a client named "sduds2", and
         use the partner name "sduds1" when authenticating to
         it.)
$ ./testing/add_entry.py
	(Will create a database entry for an example user.)
$ ./sduds.py -p 20010
        (Will run a webserver on port 20010 and the
         synchronization server on port 20011.)

For the other copy, do:

$ ./partners.py -a -s http://localhost:20000/ sduds1 sduds2 0.0
        (Adds the first instance of the program, which runs
         on port 20000, as a server named "sduds1", and use
         the partner name "sduds2" when authenticating to
         it. You need to supply the passwords you typed
         above, in reversed order. The 0.0 tells the server
	 to fully trust the other server, that means no control
         samples will be taken.)
$ ./sduds.py -p 20100 sduds1
	(Connects to the first instance of the program and
         synchronizes with it. The webserver will be run
         on port 20100. When the operation is completed, the
         program terminates.)

Now, you can see log messages that tell you that a database
entry was transmitted. Now you can run again the second
instance of the program by

$ ./sduds.py -p 20100

and visit http://localhost:20100. You will see an interface
for searching entries. If you search for "John Doe", the
transmitted entry will be displayed.