FS-9775: Some cleanup, some commenting, some fixes.

libs/libks/src/dht/ks_dht-int.h

@@ -6,21 +6,98 @@
 KS_BEGIN_EXTERN_C
 
 /**
- *
+ * Determines the appropriate endpoint to reach a remote address.
+ * If an endpoint is provided, nothing more needs to be done.
+ * If no endpoint is provided, first it will check for an active endpoint it can route though.
+ * If no active endpoint is available and autorouting is enabled it will attempt to bind a usable endpoint.
+ * @param dht pointer to the dht instance
+ * @param raddr pointer to the remote address
+ * @param endpoint dereferenced in/out pointer to the endpoint, if populated then returns immediately
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, ...
+ * @see ks_ip_route
+ * @see ks_hash_read_unlock
+ * @see ks_addr_set
+ * @see ks_dht_bind
+ */
+KS_DECLARE(ks_status_t) ks_dht_autoroute_check(ks_dht_t *dht, ks_sockaddr_t *raddr, ks_dht_endpoint_t **endpoint);
+
+/**
+ * Called internally to expire various data.
+ * Handles purging of expired and finished transactions, rotating token secrets, etc.
+ * @param dht pointer to the dht instance
+ */
+KS_DECLARE(void) ks_dht_pulse_expirations(ks_dht_t *dht);
+
+/**
+ * Called internally to send queued messages.
+ * Handles throttling of message sending to ensure system buffers are not overloaded and messages are not dropped.
+ * @param dht pointer to the dht instance
+ */
+KS_DECLARE(void) ks_dht_pulse_send(ks_dht_t *dht);
+
+/**
+ * Converts a ks_dht_nodeid_t into it's hex string representation.
+ * @param id pointer to the nodeid
+ * @param buffer pointer to the buffer able to contain at least (KS_DHT_NODEID_SIZE * 2) + 1 characters
+ * @return The pointer to the front of the populated string buffer
+ */
+KS_DECLARE(char *) ks_dht_hexid(ks_dht_nodeid_t *id, char *buffer);
+
+/**
+ * Compacts address information as per the DHT specifications.
+ * @param address pointer to the address being compacted from
+ * @param buffer pointer to the buffer containing compacted data
+ * @param buffer_length pointer to the buffer length consumed
+ * @param buffer_size max size of the buffer
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_NO_MEM
  */
 KS_DECLARE(ks_status_t) ks_dht_utility_compact_addressinfo(const ks_sockaddr_t *address,
 														   uint8_t *buffer,
 														   ks_size_t *buffer_length,
 														   ks_size_t buffer_size);
+
+/**
+ * Expands address information as per the DHT specifications.
+ * @param buffer pointer to the buffer containing compacted data
+ * @param buffer_length pointer to the buffer length consumed
+ * @param buffer_size max size of the buffer
+ * @param address pointer to the address being expanded into
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_NO_MEM, ...
+ * @see ks_addr_set_raw
+ */
 KS_DECLARE(ks_status_t) ks_dht_utility_expand_addressinfo(const uint8_t *buffer,
 														  ks_size_t *buffer_length,
 														  ks_size_t buffer_size,
 														  ks_sockaddr_t *address);
+
+/**
+ * Compacts node information as per the DHT specifications.
+ * Compacts address information after the nodeid.
+ * @param nodeid pointer to the nodeid being compacted from
+ * @param address pointer to the address being compacted from
+ * @param buffer pointer to the buffer containing compacted data
+ * @param buffer_length pointer to the buffer length consumed
+ * @param buffer_size max size of the buffer
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_NO_MEM, ...
+ * @see ks_dht_utility_compact_addressinfo
+ */
 KS_DECLARE(ks_status_t) ks_dht_utility_compact_nodeinfo(const ks_dht_nodeid_t *nodeid,
 														const ks_sockaddr_t *address,
 														uint8_t *buffer,
 														ks_size_t *buffer_length,
 														ks_size_t buffer_size);
+
+/**
+ * Expands address information as per the DHT specifications.
+ * Expands compacted address information after the nodeid.
+ * @param buffer pointer to the buffer containing compacted data
+ * @param buffer_length pointer to the buffer length consumed
+ * @param buffer_size max size of the buffer
+ * @param address pointer to the address being expanded into
+ * @param nodeid pointer to the nodeid being expanded into
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_NO_MEM, ...
+ * @see ks_dht_utility_expand_addressinfo
+ */
 KS_DECLARE(ks_status_t) ks_dht_utility_expand_nodeinfo(const uint8_t *buffer,
 													   ks_size_t *buffer_length,
 													   ks_size_t buffer_size,
@@ -28,12 +105,107 @@ KS_DECLARE(ks_status_t) ks_dht_utility_expand_nodeinfo(const uint8_t *buffer,
 													   ks_sockaddr_t *address);
 
 /**
- *
+ * Extracts a ks_dht_nodeid_t from a bencode dictionary given a string key.
+ * @param args pointer to the bencode dictionary
+ * @param key string key in the bencode dictionary to extract the value from
+ * @param nodeid dereferenced out pointer to the nodeid
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_ARG_INVALID
  */
-KS_DECLARE(void) ks_dht_pulse_expirations(ks_dht_t *dht);
-KS_DECLARE(void) ks_dht_pulse_send(ks_dht_t *dht);
+KS_DECLARE(ks_status_t) ks_dht_utility_extract_nodeid(struct bencode *args, const char *key, ks_dht_nodeid_t **nodeid);
+
+/**
+ * Extracts a ks_dht_token_t from a bencode dictionary given a string key.
+ * @param args pointer to the bencode dictionary
+ * @param key string key in the bencode dictionary to extract the value from
+ * @param nodeid dereferenced out pointer to the token
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_ARG_INVALID
+ */
+KS_DECLARE(ks_status_t) ks_dht_utility_extract_token(struct bencode *args, const char *key, ks_dht_token_t **token);
+
+/**
+ * Generates an opaque write token based on a shifting secret value, the remote address and target nodeid of interest.
+ * This token ensures that future operations can be verified to the remote peer and target id requested.
+ * @param secret rotating secret portion of the token hash
+ * @param raddr pointer to the remote address used for the ip and port in the token hash
+ * @param target pointer to the nodeid of the target used for the token hash
+ * @param token pointer to the output token being generated
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_FAIL
+ */
+KS_DECLARE(ks_status_t) ks_dht_token_generate(uint32_t secret, ks_sockaddr_t *raddr, ks_dht_nodeid_t *target, ks_dht_token_t *token);
 
+/**
+ * Verify an opaque write token matches the provided remote address and target nodeid.
+ * Handles checking against the last two secret values for the token hash.
+ * @param dht pointer to the dht instance
+ * @param raddr pointer to the remote address used for the ip and port in the token hash
+ * @param target pointer to the nodeid of the target used for the token hash
+ * @param token pointer to the input token being compared
+ * @return Either KS_TRUE if verification passes, otherwise KS_FALSE
+ */
+KS_DECLARE(ks_bool_t) ks_dht_token_verify(ks_dht_t *dht, ks_sockaddr_t *raddr, ks_dht_nodeid_t *target, ks_dht_token_t *token);
+
+/**
+ * Encodes a message for transmission as a UDP datagram and sends it.
+ * Uses the internally tracked local endpoint and remote address to route the UDP datagram.
+ * @param dht pointer to the dht instance
+ * @param message pointer to the message being sent
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, ...
+ * @see ks_socket_sendto
+ */
 KS_DECLARE(ks_status_t) ks_dht_send(ks_dht_t *dht, ks_dht_message_t *message);
+
+/**
+ * Sets up the common parts of a query message.
+ * Determines the local endpoint aware of autorouting, assigns the remote address, generates a transaction, and queues a callback.
+ * @param dht pointer to the dht instance
+ * @param ep pointer to the endpoint, may be NULL to find an endpoint or autoroute one
+ * @param raddr pointer to the remote address
+ * @param query string value of the query type, for example "ping"
+ * @param callback callback to be called when response to transaction is received
+ * @param message dereferenced out pointer to the allocated message
+ * @param args dereferenced out pointer to the allocated bencode args, may be NULL to ignore output
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_FAIL, ...
+ * @see ks_dht_autoroute_check
+ * @see ks_dht_transaction_alloc
+ * @see ks_dht_transaction_init
+ * @see ks_dht_message_alloc
+ * @see ks_dht_message_init
+ * @see ks_dht_message_query
+ * @see ks_hash_insert
+ */
+KS_DECLARE(ks_status_t) ks_dht_setup_query(ks_dht_t *dht,
+										   ks_dht_endpoint_t *ep,
+										   ks_sockaddr_t *raddr,
+										   const char *query,
+										   ks_dht_message_callback_t callback,
+										   ks_dht_message_t **message,
+										   struct bencode **args);
+
+/**
+ * Sets up the common parts of a response message.
+ * Determines the local endpoint aware of autorouting, assigns the remote address, and assigns the transaction.
+ * @param dht pointer to the dht instance
+ * @param ep pointer to the endpoint, may be NULL to find an endpoint or autoroute one
+ * @param raddr pointer to the remote address
+ * @param transactionid pointer to the buffer containing the transactionid, may be of variable size depending on the querying node
+ * @param transactionid_length length of the transactionid buffer
+ * @param message dereferenced out pointer to the allocated message
+ * @param args dereferenced out pointer to the allocated bencode args, may be NULL to ignore output
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, ...
+ * @see ks_dht_autoroute_check
+ * @see ks_dht_message_alloc
+ * @see ks_dht_message_init
+ * @see ks_dht_message_response
+ */
+KS_DECLARE(ks_status_t) ks_dht_setup_response(ks_dht_t *dht,
+											  ks_dht_endpoint_t *ep,
+											  ks_sockaddr_t *raddr,
+											  uint8_t *transactionid,
+											  ks_size_t transactionid_length,
+											  ks_dht_message_t **message,
+											  struct bencode **args);
+												
+						
 KS_DECLARE(ks_status_t) ks_dht_send_error(ks_dht_t *dht,
 										  ks_dht_endpoint_t *ep,
 										  ks_sockaddr_t *raddr,

libs/libks/src/dht/ks_dht.h

@@ -174,45 +174,176 @@ struct ks_dht_s {
 };
 
 /**
- *
+ * Allocator function for ks_dht_t.
+ * Should be used when a ks_dht_t is allocated on the heap, and may provide an external memory pool or allocate one internally.
+ * @param dht dereferenced out pointer to the allocated dht instance
+ * @param pool pointer to the memory pool used by the dht instance, may be NULL to create a new pool internally
+ * @param The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_NO_MEM
  */
 KS_DECLARE(ks_status_t) ks_dht_alloc(ks_dht_t **dht, ks_pool_t *pool);
-KS_DECLARE(ks_status_t) ks_dht_prealloc(ks_dht_t *dht, ks_pool_t *pool);
-KS_DECLARE(ks_status_t) ks_dht_free(ks_dht_t **dht);
+						
+/**
+ * Preallocator function for ks_dht_t.
+ * Should be used when a ks_dht_t is preallocated on the stack or within another structure, and must provide an external memory pool.
+ * @param dht pointer to the dht instance
+ * @param pool pointer to the memory pool used by the dht instance
+ */
+KS_DECLARE(void) ks_dht_prealloc(ks_dht_t *dht, ks_pool_t *pool);
 
+/**
+ * Deallocator function for ks_dht_t.
+ * Must be used when a ks_dht_t is allocated using ks_dht_alloc, will also destroy memory pool if it was created internally.
+ * @param dht dereferenced in/out pointer to the dht instance, NULL upon return
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, ...
+ * @see ks_dht_deinit
+ * @see ks_pool_free
+ * @see ks_pool_close
+ */
+KS_DECLARE(ks_status_t) ks_dht_free(ks_dht_t **dht);
 
+/**
+ * Constructor function for ks_dht_t.
+ * Must be used regardless of how ks_dht_t is allocated, will allocate and initialize internal state including registration of message handlers.
+ * @param dht pointer to the dht instance
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, ...
+ * @see ks_hash_create
+ * @see ks_dht_register_type
+ * @see ks_q_create
+ */
 KS_DECLARE(ks_status_t) ks_dht_init(ks_dht_t *dht);
+
+/**
+ * Destructor function for ks_dht_t.
+ * Must be used regardless of how ks_dht_t is allocated, will deallocate and deinitialize internal state.
+ * @param dht pointer to the dht instance
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, ...
+ * @see ks_dht_storageitem_deinit
+ * @see ks_dht_storageitem_free
+ * @see ks_hash_destroy
+ * @see ks_dht_message_deinit
+ * @see ks_dht_message_free
+ * @see ks_q_destroy
+ * @see ks_dht_endpoint_deinit
+ * @see ks_dht_endpoint_free
+ * @see ks_pool_free
+ */
 KS_DECLARE(ks_status_t) ks_dht_deinit(ks_dht_t *dht);
 
-KS_DECLARE(ks_status_t) ks_dht_autoroute(ks_dht_t *dht, ks_bool_t autoroute, ks_port_t port);
+/**
+ * Enable or disable (default) autorouting support.
+ * When enabled, autorouting will allow sending to remote addresses on interfaces which are not yet bound.
+ * The address will be bound with the provided autoroute port when this occurs.
+ * @param dht pointer to the dht instance
+ * @param autoroute enable or disable autorouting
+ * @param port when enabling autorouting this port will be used to bind new addresses, may be 0 to use the default DHT port
+ */
+KS_DECLARE(void) ks_dht_autoroute(ks_dht_t *dht, ks_bool_t autoroute, ks_port_t port);
 
+/**
+ * Register a callback for a specific message type.
+ * Will overwrite any duplicate handlers.
+ * @param dht pointer to the dht instance
+ * @param value string of the type text under the 'y' key of a message
+ * @param callback the callback to be called when a message matches
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_FAIL
+ */
+KS_DECLARE(ks_status_t) ks_dht_register_type(ks_dht_t *dht, const char *value, ks_dht_message_callback_t callback);
+
+/**
+ * Register a callback for a specific message query.
+ * Will overwrite any duplicate handlers.
+ * @param dht pointer to the dht instance
+ * @param value string of the type text under the 'q' key of a message
+ * @param callback the callback to be called when a message matches
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_FAIL
+ */
+KS_DECLARE(ks_status_t) ks_dht_register_query(ks_dht_t *dht, const char *value, ks_dht_message_callback_t callback);
+
+/**
+ * Register a callback for a specific message error.
+ * Will overwrite any duplicate handlers.
+ * @param dht pointer to the dht instance
+ * @param value string of the errorcode under the first item of the 'e' key of a message
+ * @param callback the callback to be called when a message matches
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_FAIL
+ */
+KS_DECLARE(ks_status_t) ks_dht_register_error(ks_dht_t *dht, const char *value, ks_dht_message_callback_t callback);
+
+/**
+ * Bind a local address and port for receiving UDP datagrams.
+ * @param dht pointer to the dht instance
+ * @param nodeid pointer to a nodeid for this endpoint, may be NULL to generate one randomly
+ * @param addr pointer to the remote address information
+ * @param dereferenced out pointer to the allocated endpoint, may be NULL to ignore endpoint
+ * @return The ks_status_t result: KS_STATUS_SUCCESS, KS_STATUS_FAIL, ...
+ * @see ks_socket_option
+ * @see ks_addr_bind
+ * @see ks_dht_endpoint_alloc
+ * @see ks_dht_endpoint_init
+ * @see ks_hash_insert
+ * @see ks_dhtrt_initroute
+ * @see ks_dhtrt_create_node
+ */
 KS_DECLARE(ks_status_t) ks_dht_bind(ks_dht_t *dht, const ks_dht_nodeid_t *nodeid, const ks_sockaddr_t *addr, ks_dht_endpoint_t **endpoint);
-KS_DECLARE(void) ks_dht_pulse(ks_dht_t *dht, int32_t timeout);
 
+/**
+ * Pulse the internals of dht.
+ * Handles receiving UDP datagrams, dispatching processing, handles expirations, throttled message sending, route table pulsing, etc.
+ * @param dht pointer to the dht instance
+ * @param timeout timeout value used when polling sockets for new UDP datagrams
+ */
+KS_DECLARE(void) ks_dht_pulse(ks_dht_t *dht, int32_t timeout);
 
-KS_DECLARE(ks_status_t) ks_dht_register_type(ks_dht_t *dht, const char *value, ks_dht_message_callback_t callback);
-KS_DECLARE(ks_status_t) ks_dht_register_query(ks_dht_t *dht, const char *value, ks_dht_message_callback_t callback);
 
 /**
  *
  */
 KS_DECLARE(ks_status_t) ks_dht_message_alloc(ks_dht_message_t **message, ks_pool_t *pool);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_prealloc(ks_dht_message_t *message, ks_pool_t *pool);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_free(ks_dht_message_t **message);
 
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_init(ks_dht_message_t *message, ks_dht_endpoint_t *ep, ks_sockaddr_t *raddr, ks_bool_t alloc_data);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_deinit(ks_dht_message_t *message);
 
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_parse(ks_dht_message_t *message, const uint8_t *buffer, ks_size_t buffer_length);
 
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_query(ks_dht_message_t *message,
 											 uint32_t transactionid,
 											 const char *query,
 											 struct bencode **args);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_response(ks_dht_message_t *message,
 												uint8_t *transactionid,
 												ks_size_t transactionid_length,
 												struct bencode **args);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_message_error(ks_dht_message_t *message,
 											 uint8_t *transactionid,
 											 ks_size_t transactionid_length,
@@ -221,21 +352,30 @@ KS_DECLARE(ks_status_t) ks_dht_message_error(ks_dht_message_t *message,
 /**
  *
  */
+KS_DECLARE(ks_status_t) ks_dht_transaction_alloc(ks_dht_transaction_t **transaction, ks_pool_t *pool);
 
 /**
  *
  */
-KS_DECLARE(ks_status_t) ks_dht_transaction_alloc(ks_dht_transaction_t **transaction, ks_pool_t *pool);
 KS_DECLARE(ks_status_t) ks_dht_transaction_prealloc(ks_dht_transaction_t *transaction, ks_pool_t *pool);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_transaction_free(ks_dht_transaction_t **transaction);
 
 KS_DECLARE(ks_status_t) ks_dht_transaction_init(ks_dht_transaction_t *transaction,
 												 ks_sockaddr_t *raddr,
 												 uint32_t transactionid,
 												 ks_dht_message_callback_t callback);
+
+/**
+ *
+ */
 KS_DECLARE(ks_status_t) ks_dht_transaction_deinit(ks_dht_transaction_t *transaction);
 
 
+
 /**
  * route table methods
  *
@@ -244,10 +384,10 @@ KS_DECLARE(ks_status_t) ks_dhtrt_initroute(ks_dhtrt_routetable_t **tableP, ks_po
 KS_DECLARE(void) ks_dhtrt_deinitroute(ks_dhtrt_routetable_t **table);
 
 KS_DECLARE(ks_status_t)        ks_dhtrt_create_node(ks_dhtrt_routetable_t* table,
-                                  ks_dht_nodeid_t nodeid,
-                                  enum ks_dht_nodetype_t type,
-                                  char* ip, unsigned short port,
-                                  ks_dht_node_t** node);
+													ks_dht_nodeid_t nodeid,
+													enum ks_dht_nodetype_t type,
+													char* ip, unsigned short port,
+													ks_dht_node_t** node);
 
 KS_DECLARE(ks_status_t)        ks_dhtrt_delete_node(ks_dhtrt_routetable_t* table, ks_dht_node_t* node);
 

libs/libks/test/testdht2.c

@@ -59,8 +59,7 @@ int main() {
   err = ks_dht_init(dht1);
   ok(err == KS_STATUS_SUCCESS);
 
-  err = ks_dht_prealloc(&dht2, dht1->pool);
-  ok(err == KS_STATUS_SUCCESS);
+  ks_dht_prealloc(&dht2, dht1->pool);
   
   err = ks_dht_init(&dht2);
   ok(err == KS_STATUS_SUCCESS);