class KhashmirBase(protocol.Factory):
"""The base Khashmir class, with base functionality and find node, no key-value mappings.
@type _Node: L{node.Node}
@ivar _Node: the knode implementation to use for this class of DHT
@type config: C{dictionary}
@ivar config: the configuration parameters for the DHT
@type pinging: C{dictionary}
@ivar pinging: the node's that are currently being pinged, keys are the
node id's, values are the Deferred or DelayedCall objects
@type port: C{int}
@ivar port: the port to listen on
@type store: L{db.DB}
@ivar store: the database to store nodes and key/value pairs in
@type node: L{node.Node}
@ivar node: this node
@type table: L{ktable.KTable}
@ivar table: the routing table
@type token_secrets: C{list} of C{string}
@ivar token_secrets: the current secrets to use to create tokens
@type stats: L{stats.StatsLogger}
@ivar stats: the statistics gatherer
@type udp: L{krpc.hostbroker}
@ivar udp: the factory for the KRPC protocol
@type listenport: L{twisted.internet.interfaces.IListeningPort}
@ivar listenport: the UDP listening port
@type next_checkpoint: L{twisted.internet.interfaces.IDelayedCall}
@ivar next_checkpoint: the delayed call for the next checkpoint
"""
_Node = KNodeBase
def __init__(self, config, cache_dir='/tmp'):
"""Initialize the Khashmir class and call the L{setup} method.
@type config: C{dictionary}
@param config: the configuration parameters for the DHT
@type cache_dir: C{string}
@param cache_dir: the directory to store all files in
(optional, defaults to the /tmp directory)
"""
self.config = None
self.pinging = {}
self.setup(config, cache_dir)
def setup(self, config, cache_dir):
"""Setup all the Khashmir sub-modules.
@type config: C{dictionary}
@param config: the configuration parameters for the DHT
@type cache_dir: C{string}
@param cache_dir: the directory to store all files in
"""
self.config = config
self.port = config['PORT']
self.store = DB(os.path.join(cache_dir, 'khashmir.' + str(self.port) + '.db'))
self.node = self._loadSelfNode('', self.port)
self.table = KTable(self.node, config)
self.token_secrets = [newID()]
self.stats = StatsLogger(self.table, self.store)
# Start listening
self.udp = krpc.hostbroker(self, self.stats, config)
self.udp.protocol = krpc.KRPC
self.listenport = reactor.listenUDP(self.port, self.udp)
# Load the routing table and begin checkpointing
self._loadRoutingTable()
self.refreshTable(force = True)
self.next_checkpoint = reactor.callLater(60, self.checkpoint)
def Node(self, id, host = None, port = None):
"""Create a new node.
@see: L{node.Node.__init__}
"""
n = self._Node(id, host, port)
n.table = self.table
n.conn = self.udp.connectionForAddr((n.host, n.port))
return n
def __del__(self):
"""Stop listening for packets."""
self.listenport.stopListening()
def _loadSelfNode(self, host, port):
"""Create this node, loading any previously saved one."""
id = self.store.getSelfNode()
if not id or not id.endswith(self.config['VERSION']):
id = newID(self.config['VERSION'])
return self._Node(id, host, port)
def checkpoint(self):
"""Perform some periodic maintenance operations."""
# Create a new token secret
self.token_secrets.insert(0, newID())
if len(self.token_secrets) > 3:
self.token_secrets.pop()
# Save some parameters for reloading
self.store.saveSelfNode(self.node.id)
self.store.dumpRoutingTable(self.table.buckets)
# DHT maintenance
self.store.expireValues(self.config['KEY_EXPIRE'])
self.refreshTable()
self.next_checkpoint = reactor.callLater(randrange(int(self.config['CHECKPOINT_INTERVAL'] * .9),
int(self.config['CHECKPOINT_INTERVAL'] * 1.1)),
self.checkpoint)
def _loadRoutingTable(self):
"""Load the previous routing table nodes from the database.
It's usually a good idea to call refreshTable(force = True) after
loading the table.
"""
nodes = self.store.getRoutingTable()
for rec in nodes:
n = self.Node(rec[0], rec[1], int(rec[2]))
self.table.insertNode(n, contacted = False)
#{ Local interface
def addContact(self, host, port, callback=None, errback=None):
"""Ping this node and add the contact info to the table on pong.
@type host: C{string}
@param host: the IP address of the node to contact
@type port: C{int}
@param port:the port of the node to contact
@type callback: C{method}
@param callback: the method to call with the results, it must take 1
parameter, the contact info returned by the node
(optional, defaults to doing nothing with the results)
@type errback: C{method}
@param errback: the method to call if an error occurs
(optional, defaults to calling the callback with the error)
"""
n = self.Node(NULL_ID, host, port)
self.sendJoin(n, callback=callback, errback=errback)
def findNode(self, id, callback):
"""Find the contact info for the K closest nodes in the global table.
@type id: C{string}
@param id: the target ID to find the K closest nodes of
@type callback: C{method}
@param callback: the method to call with the results, it must take 1
parameter, the list of K closest nodes
"""
# Mark the bucket as having been accessed
self.table.touch(id)
# Start with our node
nodes = [copy(self.node)]
# Start the finding nodes action
state = FindNode(self, id, callback, self.config, self.stats)
reactor.callLater(0, state.goWithNodes, nodes)
def insertNode(self, node, contacted = True):
"""Try to insert a node in our local table, pinging oldest contact if necessary.
If all you have is a host/port, then use L{addContact}, which calls this
method after receiving the PONG from the remote node. The reason for
the separation is we can't insert a node into the table without its
node ID. That means of course the node passed into this method needs
to be a properly formed Node object with a valid ID.
@type node: L{node.Node}
@param node: the new node to try and insert
@type contacted: C{boolean}
@param contacted: whether the new node is known to be good, i.e.
responded to a request (optional, defaults to True)
"""
# Don't add any local nodes to the routing table
if not self.config['LOCAL_OK'] and isLocal.match(node.host):
log.msg('Not adding local node to table: %s/%s' % (node.host, node.port))
return
old = self.table.insertNode(node, contacted=contacted)
if (isinstance(old, self._Node) and old.id != self.node.id and
(datetime.now() - old.lastSeen) >
timedelta(seconds=self.config['MIN_PING_INTERVAL'])):
# Bucket is full, check to see if old node is still available
df = self.sendPing(old)
df.addErrback(self._staleNodeHandler, old, node, contacted)
elif not old and not contacted:
# There's room, we just need to contact the node first
df = self.sendPing(node)
# Also schedule a future ping to make sure the node works
def rePing(newnode, self = self):
if newnode.id not in self.pinging:
self.pinging[newnode.id] = reactor.callLater(self.config['MIN_PING_INTERVAL'],
self.sendPing, newnode)
return newnode
df.addCallback(rePing)
def _staleNodeHandler(self, err, old, node, contacted):
"""The pinged node never responded, so replace it."""
self.table.invalidateNode(old)
self.insertNode(node, contacted)
return err
def nodeFailed(self, node):
"""Mark a node as having failed a request and schedule a future check.
@type node: L{node.Node}
@param node: the new node to try and insert
"""
exists = self.table.nodeFailed(node)
# If in the table, schedule a ping, if one isn't already sent/scheduled
if exists and node.id not in self.pinging:
self.pinging[node.id] = reactor.callLater(self.config['MIN_PING_INTERVAL'],
self.sendPing, node)
def sendPing(self, node):
"""Ping the node to see if it's still alive.
@type node: L{node.Node}
@param node: the node to send the join to
"""
# Check for a ping already underway
if (isinstance(self.pinging.get(node.id, None), DelayedCall) and
self.pinging[node.id].active()):
self.pinging[node.id].cancel()
elif isinstance(self.pinging.get(node.id, None), Deferred):
return self.pinging[node.id]
self.stats.startedAction('ping')
df = node.ping(self.node.id)
self.pinging[node.id] = df
df.addCallbacks(self._pingHandler, self._pingError,
callbackArgs = (node, datetime.now()),
errbackArgs = (node, datetime.now()))
return df
def _pingHandler(self, dict, node, start):
"""Node responded properly, update it and return the node object."""
self.stats.completedAction('ping', start)
del self.pinging[node.id]
# Create the node using the returned contact info
n = self.Node(dict['id'], dict['_krpc_sender'][0], dict['_krpc_sender'][1])
reactor.callLater(0, self.insertNode, n)
return n
def _pingError(self, err, node, start):
"""Error occurred, fail node."""
log.msg("action ping failed on %s/%s: %s" % (node.host, node.port, err.getErrorMessage()))
self.stats.completedAction('ping', start)
# Consume unhandled errors
self.pinging[node.id].addErrback(lambda ping_err: None)
del self.pinging[node.id]
self.nodeFailed(node)
return err
def sendJoin(self, node, callback=None, errback=None):
"""Join the DHT by pinging a bootstrap node.
@type node: L{node.Node}
@param node: the node to send the join to
@type callback: C{method}
@param callback: the method to call with the results, it must take 1
parameter, the contact info returned by the node
(optional, defaults to doing nothing with the results)
@type errback: C{method}
@param errback: the method to call if an error occurs
(optional, defaults to calling the callback with the error)
"""
if errback is None:
errback = callback
self.stats.startedAction('join')
df = node.join(self.node.id)
df.addCallbacks(self._joinHandler, self._joinError,
callbackArgs = (node, datetime.now()),
errbackArgs = (node, datetime.now()))
if callback:
df.addCallbacks(callback, errback)
def _joinHandler(self, dict, node, start):
"""Node responded properly, extract the response."""
self.stats.completedAction('join', start)
# Create the node using the returned contact info
n = self.Node(dict['id'], dict['_krpc_sender'][0], dict['_krpc_sender'][1])
reactor.callLater(0, self.insertNode, n)
return (dict['ip_addr'], dict['port'])
def _joinError(self, err, node, start):
"""Error occurred, fail node."""
log.msg("action join failed on %s/%s: %s" % (node.host, node.port, err.getErrorMessage()))
self.stats.completedAction('join', start)
self.nodeFailed(node)
return err
def findCloseNodes(self, callback=lambda a: None):
"""Perform a findNode on the ID one away from our own.
This will allow us to populate our table with nodes on our network
closest to our own. This is called as soon as we start up with an
empty table.
@type callback: C{method}
@param callback: the method to call with the results, it must take 1
parameter, the list of K closest nodes
(optional, defaults to doing nothing with the results)
"""
id = self.node.id[:-1] + chr((ord(self.node.id[-1]) + 1) % 256)
self.findNode(id, callback)
def refreshTable(self, force = False):
"""Check all the buckets for those that need refreshing.
@param force: refresh all buckets regardless of last bucket access time
(optional, defaults to False)
"""
def callback(nodes):
pass
for bucket in self.table.buckets:
if force or (datetime.now() - bucket.lastAccessed >
timedelta(seconds=self.config['BUCKET_STALENESS'])):
# Choose a random ID in the bucket and try and find it
id = newIDInRange(bucket.min, bucket.max)
self.findNode(id, callback)
def shutdown(self):
"""Closes the port and cancels pending later calls."""
self.listenport.stopListening()
try:
self.next_checkpoint.cancel()
except:
pass
for nodeid in self.pinging.keys():
if isinstance(self.pinging[nodeid], DelayedCall) and self.pinging[nodeid].active():
self.pinging[nodeid].cancel()
del self.pinging[nodeid]
self.store.close()
def getStats(self):
"""Gather the statistics for the DHT."""
return self.stats.formatHTML()
#{ Remote interface
def krpc_ping(self, id, _krpc_sender = None):
"""Pong with our ID.
@type id: C{string}
@param id: the node ID of the sender node
@type _krpc_sender: (C{string}, C{int})
@param _krpc_sender: the sender node's IP address and port
"""
if _krpc_sender is not None:
n = self.Node(id, _krpc_sender[0], _krpc_sender[1])
reactor.callLater(0, self.insertNode, n, False)
return {"id" : self.node.id}
def krpc_join(self, id, _krpc_sender = None):
"""Add the node by responding with its address and port.
@type id: C{string}
@param id: the node ID of the sender node
@type _krpc_sender: (C{string}, C{int})
@param _krpc_sender: the sender node's IP address and port
"""
if _krpc_sender is not None:
n = self.Node(id, _krpc_sender[0], _krpc_sender[1])
reactor.callLater(0, self.insertNode, n, False)
else:
_krpc_sender = ('127.0.0.1', self.port)
return {"ip_addr" : _krpc_sender[0], "port" : _krpc_sender[1], "id" : self.node.id}
def krpc_find_node(self, id, target, _krpc_sender = None):
"""Find the K closest nodes to the target in the local routing table.
@type target: C{string}
@param target: the target ID to find nodes for
@type id: C{string}
@param id: the node ID of the sender node
@type _krpc_sender: (C{string}, C{int})
@param _krpc_sender: the sender node's IP address and port
"""
if _krpc_sender is not None:
n = self.Node(id, _krpc_sender[0], _krpc_sender[1])
reactor.callLater(0, self.insertNode, n, False)
else:
_krpc_sender = ('127.0.0.1', self.port)
nodes = self.table.findNodes(target)
nodes = map(lambda node: node.contactInfo(), nodes)
token = sha(self.token_secrets[0] + _krpc_sender[0]).digest()
return {"nodes" : nodes, "token" : token, "id" : self.node.id}
