README.txt

   1 [Note: I have no idea how up to date the code examples are -- icepick ]
   2
   3 Khashmir is a distributed hash table that uses an XOR distance metric and a
   4 routing table similar to Kademlia [1].  Use Khashmir to build distributed
   5 applications.  Note that Khashmir currently isn't very attack resistant.
   6
   7   1 - http://kademlia.scs.cs.nyu.edu/
   8
   9 Khashmir is implemented in Python using the Twisted [2] asynchronous networking
  10 framework.  Network deliver is done using UDP.  PySQLite is used for each
  11 peer's backing store of keys and values.  The backing store is currently
  12 held in memory but it could easily be placed on disk.  Values expire after
  13 24 hours, by default.  Each peer stores multiple values for a key and
  14 currently returns all available values when requested.
  15
  16   2 - http://twistedmatrix.com
  17
  18 If you just want to watch it build a test network of peers, run "python
  19 khashmir.py <num peers>" This script will create the specified number of
  20 peers, give each one three random contacts, tell each one to find the
  21 closest nodes, then pick a random peer and have it find another random peer
  22 (ten times), then pick a random peer to insert a key/value and have three
  23 random peers try to find it (ten times.)
  24
  25 quick example:
  26
  27 >>> k = khashmir.test_one('<ip>', 4444)  # choose any port
  28
  29 - which is the same thing as -
  30
  31 >>> import thread, khashmir
  32 >>> k = khashmir.Khashmir('<ip>', <port>) # choose any port
  33 >>> thread.start_new_thread(k.app.run, ())
  34
  35
  36 If you want to make another peer in the same session, use
  37
  38 >>> peer = khashmir.Khashmir(host, port)
  39
  40 then do
  41
  42 >>> peer.app.run()
  43
  44 to register with the already running thread.
  45
  46
  47 Now you need some contacts.  Add as some contacts and try to find close
  48 nodes in the network.
  49
  50 >>> k.addContact('127.0.0.1', 8080)  # locate another peer
  51 >>> k.findCloseNodes()  # query the network to bootstrap our table
  52
  53 Keys are always 20-character strings (sha1 hashes) currently there is no
  54 limit to value sizes, something will go in ASAP
  55
  56 Now try storing and retrieving values.
  57
  58 # callback returns node info dictionaries and actual connection information
  59 # for peers that accepted the value. Currently finds the K closest nodes and
  60 # makes one attempt to store them
  61 >>> k.storeValueForKey(key, value, callback=None)
  62
  63 # callback returns lists of values, will fire multiple times, last time will
  64 # be an empty list
  65 >>> k.valueForKey(key, callback)
  66
  67
  68
  69 TWEAKABLE SETTINGS:
  70
  71 ktable.py:
  72         K - the size of routing table buckets, how many nodes to return
  73             in response to find-node/value request, and how many nodes to issue
  74             storeValue to; default is 8, which should work for hundreds of
  75             nodes, you might want to bump it if you think your network is going
  76             to be large
  77
  78 A bunch of other tweakables are in const.py
  79