Distributed Hash Table

Data Structures
struct	lws_dht_hash
struct	lws_dht_msg
struct	lws_dht_stats
struct	lws_dht_verb_dispatch_args
struct	lws_dht_consensus_info
struct	lws_dht_error_info
struct	lws_dht_info
struct	lws_dht_node_info

Macros
#define	LWS_DHT_SHA1_HASH_LEN   20
#define	LWS_DHT_STAT_BUCKETS   48
#define	DHT_MAX_PEERS   2048
#define	DHT_MAX_HASHES   16384
#define	DHT_MAX_HASHES_PER_SOURCE   (DHT_MAX_HASHES / 16)
#define	DHT_MAX_SEARCHES   1024
#define	DHT_SEARCH_EXPIRE_TIME   (62 * 60)

Typedefs
typedef struct lws_dht_hash	lws_dht_hash_t
typedef void	lws_dht_callback_t(void *closure, int event, const lws_dht_hash_t *info_hash, const void *data, size_t data_len, const struct sockaddr *from, size_t fromlen)
typedef int	lws_dht_blacklist_cb_t(const struct sockaddr *sa, size_t salen)
typedef void	lws_dht_hash_cb_t(void *hash_return, int hash_size, const void *v1, int len1, const void *v2, int len2, const void *v3, int len3)
typedef void	lws_dht_capture_announce_cb_t(struct lws_dht_ctx *ctx, lws_dht_hash_t *hash, const struct sockaddr *fromaddr, unsigned short prt)
typedef struct lws_dht_info	lws_dht_info_t
typedef struct lws_dht_node_info	lws_dht_node_info_t
typedef int(*	lws_dht_node_cb_t) (void *user, const lws_dht_node_info_t *ni)

Enumerations
enum	{   LWS_DHT_HASH_TYPE_UNKNOWN = 0 , LWS_DHT_HASH_TYPE_SHA1 = 0x11 , LWS_DHT_HASH_TYPE_SHA256 = 0x12 , LWS_DHT_HASH_TYPE_SHA512 = 0x13 ,   LWS_DHT_HASH_TYPE_BLAKE3 = 0x1e }
enum	lws_dht_verb_result_t {   LWS_DHT_VERB_RESULT_PROCEED = 0 , LWS_DHT_VERB_RESULT_DROP_OLDER = 1 , LWS_DHT_VERB_RESULT_REPLACE_OLDER = 2 , LWS_DHT_VERB_RESULT_PENDING_ASYNC = 3 ,   LWS_DHT_VERB_RESULT_PASS = 4 , LWS_DHT_VERB_RESULT_ERROR = -1 }
enum	lws_dht_event_t {   LWS_DHT_EVENT_NONE , LWS_DHT_EVENT_VALUES , LWS_DHT_EVENT_VALUES6 , LWS_DHT_EVENT_SEARCH_DONE ,   LWS_DHT_EVENT_SEARCH_DONE6 , LWS_DHT_EVENT_EXTERNAL_ADDR , LWS_DHT_EVENT_EXTERNAL_ADDR6 , LWS_DHT_EVENT_DATA ,   LWS_DHT_EVENT_WRITE_COMPLETED , LWS_DHT_EVENT_WRITE_FAILED , LWS_DHT_EVENT_NOTIFY , LWS_DHT_EVENT_TOKEN ,   LWS_DHT_EVENT_ERROR , LWS_DHT_EVENT_WRITEABLE }
enum	lws_dht_send_result { LWS_DHT_SEND_QUEUED = 0 , LWS_DHT_SEND_REFUSED = 1 , LWS_DHT_SEND_BUSY = 2 }

Functions
LWS_VISIBLE LWS_EXTERN lws_dht_hash_t *	lws_dht_hash_create (int type, int len, const uint8_t *data)
LWS_VISIBLE LWS_EXTERN void	lws_dht_hash_destroy (lws_dht_hash_t **p)
LWS_VISIBLE LWS_EXTERN int	lws_dht_get_stats (struct lws_vhost *vh, struct lws_dht_stats *current, const struct lws_dht_stats **history, int *head)
LWS_VISIBLE LWS_EXTERN int	lws_dht_send_subscribe (struct lws_dht_ctx *ctx, const struct sockaddr *sa, size_t salen, const lws_dht_hash_t *infohash, int want, int confirm)
LWS_VISIBLE LWS_EXTERN int	lws_dht_send_subscribe_confirm (struct lws_dht_ctx *ctx, const struct sockaddr *sa, size_t salen, uint8_t *tid, size_t tid_len, const lws_dht_hash_t *infohash, uint8_t *token, size_t token_len, const uint8_t *sha256, int confirm)
LWS_VISIBLE LWS_EXTERN int	lws_dht_send_ack (struct lws_dht_ctx *ctx, const struct sockaddr *sa, size_t salen, const uint8_t *tid, size_t tid_len)
LWS_VISIBLE LWS_EXTERN int	lws_dht_send_notify (struct lws_dht_ctx *ctx, const struct sockaddr *sa, size_t salen, const uint8_t *tid, size_t tid_len, const lws_dht_hash_t *infohash, const uint8_t *sha256, const uint8_t *payload, size_t payload_len)
LWS_VISIBLE LWS_EXTERN int	lws_dht_msg_parse (const char *in, size_t len, struct lws_dht_msg *out)
LWS_VISIBLE LWS_EXTERN int	lws_dht_valid_domain_name (const char *domain)
LWS_VISIBLE LWS_EXTERN int	lws_dht_msg_gen (char *out, size_t len, const char *verb, const char *hash, unsigned long long offset, unsigned long long len_val)
LWS_VISIBLE LWS_EXTERN int	lws_dht_register_verbs (struct lws_dht_ctx *ctx, const char **verbs, int count, const struct lws_protocols *protocol)
LWS_VISIBLE LWS_EXTERN int	lws_dht_notify_subscribers (struct lws_dht_ctx *ctx, const lws_dht_hash_t *hash, const uint8_t *sha256, const uint8_t *payload, size_t payload_len)
LWS_VISIBLE LWS_EXTERN struct lws_dht_ctx *	lws_dht_create (const lws_dht_info_t *info)
LWS_VISIBLE LWS_EXTERN void *	lws_dht_get_closure (struct lws_dht_ctx *ctx)
LWS_VISIBLE LWS_EXTERN const lws_dht_hash_t *	lws_dht_get_myid (struct lws_dht_ctx *ctx)
LWS_VISIBLE LWS_EXTERN void	lws_dht_destroy (struct lws_dht_ctx **pctx)
LWS_VISIBLE LWS_EXTERN struct lws_dht_ctx *	lws_dht_get_by_name (struct lws_vhost *vhost, const char *name)
LWS_VISIBLE LWS_EXTERN int	lws_dht_insert_node (struct lws_dht_ctx *ctx, const lws_dht_hash_t *id, struct sockaddr *sa, size_t salen)
LWS_VISIBLE LWS_EXTERN int	lws_dht_ping_node (struct lws_dht_ctx *ctx, struct sockaddr *sa, size_t salen)
LWS_VISIBLE LWS_EXTERN void	lws_dht_test_external_ips (struct lws_dht_ctx *ctx)
LWS_VISIBLE LWS_EXTERN int	lws_dht_send_data (struct lws_dht_ctx *ctx, const struct sockaddr *dest, const void *data, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_dht_send_data_at (struct lws_dht_ctx *ctx, const struct sockaddr *dest, uint64_t offset, const void *data, size_t len)
LWS_VISIBLE LWS_EXTERN struct lws_transport_sequencer *	lws_dht_get_ts (struct lws_dht_ctx *ctx, const struct sockaddr *dest, size_t salen, int create)
LWS_VISIBLE LWS_EXTERN int	lws_dht_search (struct lws_dht_ctx *ctx, const lws_dht_hash_t *id, int port, int af, lws_dht_callback_t *callback, void *closure)
LWS_VISIBLE LWS_EXTERN int	lws_dht_nodes (struct lws_dht_ctx *ctx, int af, int *good_return, int *dubious_return, int *cached_return, int *incoming_return)
LWS_VISIBLE LWS_EXTERN int	lws_dht_foreach_node (struct lws_dht_ctx *ctx, int af, lws_dht_node_cb_t cb, void *user)
LWS_VISIBLE LWS_EXTERN int	lws_dht_foreach_search_node (struct lws_dht_ctx *ctx, const lws_dht_hash_t *target, int af, lws_dht_node_cb_t cb, void *user)
LWS_VISIBLE LWS_EXTERN void	lws_dht_dump_tables (struct lws_dht_ctx *ctx)
LWS_VISIBLE LWS_EXTERN int	lws_dht_get_nodes (struct lws_dht_ctx *ctx, struct sockaddr_in *sin, int *num, struct sockaddr_in6 *sin6, int *num6)
LWS_VISIBLE LWS_EXTERN int	lws_dht_get_external_addr (struct lws_dht_ctx *ctx, struct sockaddr_storage *ss, size_t *sslen)
LWS_VISIBLE LWS_EXTERN lws_dht_hash_t *	lws_dht_bep42_id (struct lws_context *cx, const struct sockaddr *sa, uint8_t rand, int type, int len)
LWS_VISIBLE LWS_EXTERN int	lws_dht_same_host (const struct sockaddr *a, const struct sockaddr *b)
LWS_VISIBLE LWS_EXTERN int	lws_dht_bep42_check (const lws_dht_hash_t *id, const struct sockaddr *sa)
LWS_VISIBLE LWS_EXTERN int	lws_dht_get_fallback_node (struct lws_context *cx, const char *custom_path, char *result, size_t result_len)

Variables
const struct lws_protocols	lws_dht_protocol

Detailed Description

Distributed Hash Table (DHT) API

Lws provides a Mainline DHT implementation that can be used to track external IP addresses and find nodes/peers in a P2P network.

---

Data Structure Documentation

lws_dht_hash

struct lws_dht_hash

struct lws_dht_hash - DHT hash/ID structure

Parameters

type	LWS_DHT_HASH_TYPE_...
len	length of the ID in bytes
id	the ID bytes

Definition at line 52 of file lws-dht.h.

Collaboration diagram for lws_dht_hash:

Data Fields
uint8_t	type
uint8_t	len
uint8_t	id[]

lws_dht_msg

struct lws_dht_msg

Definition at line 104 of file lws-dht.h.

Collaboration diagram for lws_dht_msg:

Data Fields
char	verb[16]
char	hash[LWS_GENHASH_LARGEST *2+1]
unsigned long long	offset
unsigned long long	len
const void *	payload
size_t	payload_len

lws_dht_stats

struct lws_dht_stats

struct lws_dht_stats - tracking metrics for DHT operation volumes

Definition at line 127 of file lws-dht.h.

Collaboration diagram for lws_dht_stats:

Data Fields
uint32_t	tx_ping
uint32_t	tx_pong
uint32_t	tx_find_node
uint32_t	tx_get_peers
uint32_t	tx_announce_peer
uint32_t	tx_put
uint32_t	tx_get
uint32_t	rx_ping
uint32_t	rx_pong
uint32_t	rx_find_node
uint32_t	rx_get_peers
uint32_t	rx_announce_peer
uint32_t	rx_put
uint32_t	rx_get
uint32_t	rx_drops
uint32_t	peer_count

lws_dht_verb_dispatch_args

struct lws_dht_verb_dispatch_args

Definition at line 160 of file lws-dht.h.

Collaboration diagram for lws_dht_verb_dispatch_args:

Data Fields
struct lws_dht_ctx *	ctx
const struct lws_dht_msg *	msg
const struct sockaddr *	from
size_t	fromlen
lws_dht_verb_result_t	out_precedence

lws_dht_consensus_info

struct lws_dht_consensus_info

struct lws_dht_consensus_info - Passed as data for LWS_DHT_EVENT_EXTERNAL_ADDR(6)

Definition at line 370 of file lws-dht.h.

Collaboration diagram for lws_dht_consensus_info:

Data Fields
struct sockaddr_storage	ss
size_t	sslen
int	num_peers
struct sockaddr_storage	peer_ss[8]

lws_dht_error_info

struct lws_dht_error_info

struct lws_dht_error_info - Passed as data for LWS_DHT_EVENT_ERROR

A peer's "y":"e" reply to something we sent it: the BEP 5 code (eg, 203, protocol error) and the peer's description of what it refused. The tid and message point into the datagram being processed, are not NUL-terminated, and are only valid during the callback. The sender is the callback's from, which is as unauthenticated as any datagram source.

Definition at line 386 of file lws-dht.h.

Collaboration diagram for lws_dht_error_info:

Data Fields
const uint8_t *	tid	tid of the query being refused
size_t	tid_len
const char *	message	the peer's description
size_t	message_len
int	code	BEP 5 error code

lws_dht_info

struct lws_dht_info

struct lws_dht_info - Initialization parameters for DHT

Parameters

vhost	vhost to attach UDP wsi to
cb	callback for DHT events
closure	user-defined closure for cb
id	DHT ID (optional, NULL = random)
v	version string (optional, NULL = default)
port	UDP port to listen on
ipv6	enable IPv6
legacy	if set, on wire: no multihash, 20-byte assumed
allow_private_ads	if set, peers at private, loopback or link-local addresses are admitted to the routing table and exempt from the BEP42 id check (for a LAN deployment, or tests on loopback); by default such peers are refused, as any node on the public internet should
aux	0 (sha1), or MULTIHASH_TYPE_...
iface	interface to bind to
blacklist_cb	(optional) user blacklist cb
hash_cb	(optional) user hash cb
capture_announce_cb	(optional) user capture announce cb
max_hashes_per_source	0 for the default, DHT_MAX_HASHES_PER_SOURCE, or how many info hashes one source host (an IPv4 address or an IPv6 /64) may have us start storing peers or subscribers for. Hashes that are already stored take anybody's announce or subscription; this stops one host filling the DHT_MAX_HASHES table so no new hash can be stored for anyone else.
blacklist_secs	0 for the default, 600, or how many seconds an endpoint the DHT blacklists itself stays blacklisted. It does that to a peer that proved it receives from us and then broke the protocol, eg, acknowledged data we never sent. This does not affect what blacklist_cb decides.

Definition at line 426 of file lws-dht.h.

Collaboration diagram for lws_dht_info:

Data Fields
struct lws_vhost *	vhost
lws_dht_callback_t *	cb
void *	closure
const lws_dht_hash_t *	id
const char *	v
const char *	name
int	port
uint8_t	ipv6:1
uint8_t	legacy:1
uint8_t	allow_private_ads:1
uint8_t	aux
const char *	iface
const char *	fallback_nodes_path
lws_dht_blacklist_cb_t *	blacklist_cb
lws_dht_hash_cb_t *	hash_cb
lws_dht_capture_announce_cb_t *	capture_announce_cb
unsigned int	max_hashes_per_source
unsigned int	blacklist_secs

lws_dht_node_info

struct lws_dht_node_info

struct lws_dht_node_info - one routing table entry, for lws_dht_foreach_node()

Parameters

id	the node id it uses
sa	the endpoint we know it at
salen	length of sa
heard	seconds since anything came from it, or -1 if nothing has
replied	seconds since it last answered something we sent it, or -1 if it never has
pinged	how many requests we have sent it since it last answered
good	whether it counts as good, eg, for lws_dht_get_nodes()
bep42_ok	whether its id is bound to its address as BEP42 says (or its address is private)

Everything pointed to is only valid during the callback.

Definition at line 645 of file lws-dht.h.

Collaboration diagram for lws_dht_node_info:

Data Fields
const lws_dht_hash_t *	id
const struct sockaddr *	sa
size_t	salen
long	heard
long	replied
int	pinged
uint8_t	good:1
uint8_t	bep42_ok:1

Macro Definition Documentation

LWS_DHT_SHA1_HASH_LEN

#define LWS_DHT_SHA1_HASH_LEN   20

#include <lws-dht.h>

Definition at line 66 of file lws-dht.h.

LWS_DHT_STAT_BUCKETS

#define LWS_DHT_STAT_BUCKETS   48

#include <lws-dht.h>

Definition at line 122 of file lws-dht.h.

DHT_MAX_PEERS

#define DHT_MAX_PEERS   2048

#include <lws-dht.h>

Definition at line 322 of file lws-dht.h.

DHT_MAX_HASHES

#define DHT_MAX_HASHES   16384

#include <lws-dht.h>

Definition at line 325 of file lws-dht.h.

DHT_MAX_HASHES_PER_SOURCE

#define DHT_MAX_HASHES_PER_SOURCE   (DHT_MAX_HASHES / 16)

#include <lws-dht.h>

Definition at line 331 of file lws-dht.h.

DHT_MAX_SEARCHES

#define DHT_MAX_SEARCHES   1024

#include <lws-dht.h>

Definition at line 334 of file lws-dht.h.

DHT_SEARCH_EXPIRE_TIME

#define DHT_SEARCH_EXPIRE_TIME   (62 * 60)

#include <lws-dht.h>

Definition at line 337 of file lws-dht.h.

Typedef Documentation

lws_dht_hash_t

typedef struct lws_dht_hash lws_dht_hash_t

#include <lws-dht.h>

struct lws_dht_hash - DHT hash/ID structure

Parameters

type	LWS_DHT_HASH_TYPE_...
len	length of the ID in bytes
id	the ID bytes

lws_dht_callback_t

typedef void lws_dht_callback_t(void *closure, int event, const lws_dht_hash_t *info_hash, const void *data, size_t data_len, const struct sockaddr *from, size_t fromlen)

#include <lws-dht.h>

lws_dht_callback_t() - DHT event callback

Parameters

closure	user-defined closure pointer
event	LWS_DHT_EVENT_...
info_hash	the hash related to the event
data	event-specific data
data_len	length of event-specific data

Definition at line 102 of file lws-dht.h.

lws_dht_blacklist_cb_t

typedef int lws_dht_blacklist_cb_t(const struct sockaddr *sa, size_t salen)

#include <lws-dht.h>

lws_dht_blacklist_cb_t() - DHT blacklist check callback

Parameters

sa	sockaddr to check
salen	length of sockaddr

Returns

0 if the address is allowed, non-zero if it is blacklisted.

Definition at line 288 of file lws-dht.h.

lws_dht_hash_cb_t

typedef void lws_dht_hash_cb_t(void *hash_return, int hash_size, const void *v1, int len1, const void *v2, int len2, const void *v3, int len3)

#include <lws-dht.h>

lws_dht_hash_cb_t() - Custom hash function for DHT

Parameters

hash_return	where to store the hash result
hash_size	size of the hash result buffer
v1	first data chunk
len1	length of first chunk
v2	second data chunk (optional)
len2	length of second chunk
v3	third data chunk (optional)
len3	length of third chunk

Definition at line 303 of file lws-dht.h.

lws_dht_capture_announce_cb_t

typedef void lws_dht_capture_announce_cb_t(struct lws_dht_ctx *ctx, lws_dht_hash_t *hash, const struct sockaddr *fromaddr, unsigned short prt)

#include <lws-dht.h>

lws_dht_capture_announce_cb_t() - Captured announce callback

Parameters

ctx	DHT context
hash	the announced hash
fromaddr	where the announce came from
prt	the port announced

Definition at line 317 of file lws-dht.h.

lws_dht_info_t

typedef struct lws_dht_info lws_dht_info_t

#include <lws-dht.h>

struct lws_dht_info - Initialization parameters for DHT

Parameters

vhost	vhost to attach UDP wsi to
cb	callback for DHT events
closure	user-defined closure for cb
id	DHT ID (optional, NULL = random)
v	version string (optional, NULL = default)
port	UDP port to listen on
ipv6	enable IPv6
legacy	if set, on wire: no multihash, 20-byte assumed
allow_private_ads	if set, peers at private, loopback or link-local addresses are admitted to the routing table and exempt from the BEP42 id check (for a LAN deployment, or tests on loopback); by default such peers are refused, as any node on the public internet should
aux	0 (sha1), or MULTIHASH_TYPE_...
iface	interface to bind to
blacklist_cb	(optional) user blacklist cb
hash_cb	(optional) user hash cb
capture_announce_cb	(optional) user capture announce cb
max_hashes_per_source	0 for the default, DHT_MAX_HASHES_PER_SOURCE, or how many info hashes one source host (an IPv4 address or an IPv6 /64) may have us start storing peers or subscribers for. Hashes that are already stored take anybody's announce or subscription; this stops one host filling the DHT_MAX_HASHES table so no new hash can be stored for anyone else.
blacklist_secs	0 for the default, 600, or how many seconds an endpoint the DHT blacklists itself stays blacklisted. It does that to a peer that proved it receives from us and then broke the protocol, eg, acknowledged data we never sent. This does not affect what blacklist_cb decides.

lws_dht_node_info_t

typedef struct lws_dht_node_info lws_dht_node_info_t

#include <lws-dht.h>

struct lws_dht_node_info - one routing table entry, for lws_dht_foreach_node()

Parameters

id	the node id it uses
sa	the endpoint we know it at
salen	length of sa
heard	seconds since anything came from it, or -1 if nothing has
replied	seconds since it last answered something we sent it, or -1 if it never has
pinged	how many requests we have sent it since it last answered
good	whether it counts as good, eg, for lws_dht_get_nodes()
bep42_ok	whether its id is bound to its address as BEP42 says (or its address is private)

Everything pointed to is only valid during the callback.

lws_dht_node_cb_t

typedef int(* lws_dht_node_cb_t) (void *user, const lws_dht_node_info_t *ni)

#include <lws-dht.h>

Definition at line 656 of file lws-dht.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <lws-dht.h>

Enumerator
LWS_DHT_HASH_TYPE_UNKNOWN
LWS_DHT_HASH_TYPE_SHA1
LWS_DHT_HASH_TYPE_SHA256
LWS_DHT_HASH_TYPE_SHA512
LWS_DHT_HASH_TYPE_BLAKE3

Definition at line 58 of file lws-dht.h.

     {
        LWS_DHT_HASH_TYPE_UNKNOWN       = 0,
        LWS_DHT_HASH_TYPE_SHA1          = 0x11, /* 20 bytes */
        LWS_DHT_HASH_TYPE_SHA256        = 0x12, /* 32 bytes */
        LWS_DHT_HASH_TYPE_SHA512        = 0x13, /* 64 bytes */
        LWS_DHT_HASH_TYPE_BLAKE3        = 0x1e, /* 32 bytes */
};

lws_dht_verb_result_t

enum lws_dht_verb_result_t

#include <lws-dht.h>

Enumerator
LWS_DHT_VERB_RESULT_PROCEED
LWS_DHT_VERB_RESULT_DROP_OLDER
LWS_DHT_VERB_RESULT_REPLACE_OLDER
LWS_DHT_VERB_RESULT_PENDING_ASYNC
LWS_DHT_VERB_RESULT_PASS
LWS_DHT_VERB_RESULT_ERROR

Definition at line 113 of file lws-dht.h.

             {
        LWS_DHT_VERB_RESULT_PROCEED = 0,
        LWS_DHT_VERB_RESULT_DROP_OLDER = 1,    /* The incoming object is older than what we have; reject it. */
        LWS_DHT_VERB_RESULT_REPLACE_OLDER = 2, /* The incoming object is newer; accept and replace. */
        LWS_DHT_VERB_RESULT_PENDING_ASYNC = 3, /* Validation is asynchronous; hold off on core DHT actions. */
        LWS_DHT_VERB_RESULT_PASS = 4,          /* Pass to the next registered plugin handler */
        LWS_DHT_VERB_RESULT_ERROR = -1
} lws_dht_verb_result_t;

lws_dht_event_t

enum lws_dht_event_t

#include <lws-dht.h>

enum lws_dht_event_t - DHT events reported via callback

Enumerator
LWS_DHT_EVENT_NONE
LWS_DHT_EVENT_VALUES	Peers for requested hash found
LWS_DHT_EVENT_VALUES6	IPv6 peers for requested hash found
LWS_DHT_EVENT_SEARCH_DONE	Search operation completed
LWS_DHT_EVENT_SEARCH_DONE6	IPv6 search operation completed
LWS_DHT_EVENT_EXTERNAL_ADDR	External IPv4 address determined
LWS_DHT_EVENT_EXTERNAL_ADDR6	External IPv6 address determined
LWS_DHT_EVENT_DATA	Arbitrary data payload received
LWS_DHT_EVENT_WRITE_COMPLETED	Reliable write successful
LWS_DHT_EVENT_WRITE_FAILED	Reliable write failed
LWS_DHT_EVENT_NOTIFY	Notification received
LWS_DHT_EVENT_TOKEN	Security token received from a peer, in reply to our subscribe or get_peers request to it; info_hash is the hash that request was for
LWS_DHT_EVENT_ERROR	A peer answered a query of ours with a BEP 5 error reply; data is a struct lws_dht_error_info
LWS_DHT_EVENT_WRITEABLE	lws_dht_send_data() to the peer at from returned LWS_DHT_SEND_BUSY, and it has since acknowledged enough that there is room: send again

Definition at line 342 of file lws-dht.h.

             {
        LWS_DHT_EVENT_NONE,
        LWS_DHT_EVENT_VALUES,           
        LWS_DHT_EVENT_VALUES6,          
        LWS_DHT_EVENT_SEARCH_DONE,      
        LWS_DHT_EVENT_SEARCH_DONE6,     
        LWS_DHT_EVENT_EXTERNAL_ADDR,    
        LWS_DHT_EVENT_EXTERNAL_ADDR6,   
        LWS_DHT_EVENT_DATA,             
        LWS_DHT_EVENT_WRITE_COMPLETED,  
        LWS_DHT_EVENT_WRITE_FAILED,     
        LWS_DHT_EVENT_NOTIFY,           
        LWS_DHT_EVENT_TOKEN,            
        LWS_DHT_EVENT_ERROR,            
        LWS_DHT_EVENT_WRITEABLE,        
} lws_dht_event_t;

lws_dht_send_result

enum lws_dht_send_result

#include <lws-dht.h>

enum lws_dht_send_result - what became of a message given to lws_dht_send_data()

Enumerator
LWS_DHT_SEND_QUEUED	taken: it is sent reliably, and the session ends with LWS_DHT_EVENT_WRITE_COMPLETED or _FAILED
LWS_DHT_SEND_REFUSED	it can't be sent to that peer: it is blacklisted, the address family is unusable, or no sequencer can be had for it
LWS_DHT_SEND_BUSY	not taken for now: the peer has not acknowledged enough of what we already sent it to leave room. LWS_DHT_EVENT_WRITEABLE for that peer comes when there is, or LWS_DHT_EVENT_WRITE_FAILED if the session fails first

Definition at line 534 of file lws-dht.h.

                         {
        LWS_DHT_SEND_QUEUED     = 0,
        LWS_DHT_SEND_REFUSED    = 1,
        LWS_DHT_SEND_BUSY       = 2,
};

Function Documentation

lws_dht_hash_create()

LWS_VISIBLE LWS_EXTERN lws_dht_hash_t * lws_dht_hash_create	(	int	type,
		int	len,
		const uint8_t *	data )

#include <lws-dht.h>

lws_dht_hash_create() - Create a DHT hash from data

Parameters

type	LWS_DHT_HASH_TYPE_...
len	length of data
data	the data to hash or use as ID

This creates a new lws_dht_hash_t object on the heap.

Returns

pointer to the new hash, or NULL on failure.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_hash_destroy()

LWS_VISIBLE LWS_EXTERN void lws_dht_hash_destroy

(

lws_dht_hash_t **

p

)

#include <lws-dht.h>

lws_dht_hash_destroy() - Destroy a DHT hash

Parameters

p	pointer to the hash pointer to destroy

Frees the hash and sets the pointer to NULL.

lws_dht_get_stats()

LWS_VISIBLE LWS_EXTERN int lws_dht_get_stats	(	struct lws_vhost *	vh,
		struct lws_dht_stats *	current,
		const struct lws_dht_stats **	history,
		int *	head )

#include <lws-dht.h>

lws_dht_get_stats() - Retrieve current and historical DHT metrics

Parameters

vh	the vhost the DHT is running on
current	Pointer to store current un-rotated metrics, or NULL
history	Pointer to receive the internal history array pointer
head	Receives the index of the oldest history frame (next to be overwritten)

lws_dht_send_subscribe()

LWS_VISIBLE LWS_EXTERN int lws_dht_send_subscribe	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	sa,
		size_t	salen,
		const lws_dht_hash_t *	infohash,
		int	want,
		int	confirm )

#include <lws-dht.h>

lws_dht_send_subscribe() - ask a node for a token to subscribe to a hash

Parameters

ctx	the DHT
sa	the node's address
salen	length of sa
infohash	the hash to subscribe to
want	0, or the address families wanted in the reply's nodes
confirm	unused

The node answers like a get_peers, with nodes and a token. The library chooses the transaction id itself and remembers it, and infohash, with sa, so it can route that reply: the token surfaces as LWS_DHT_EVENT_TOKEN with infohash as its info_hash, to be returned in lws_dht_send_subscribe_confirm() for that hash. Only the one reply to this request, from sa and within the ping timeout, produces the event; a token in any other reply is not reported. A node can only have a few subscribes awaiting their reply at once: the oldest one gives way.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_send_subscribe_confirm()

LWS_VISIBLE LWS_EXTERN int lws_dht_send_subscribe_confirm	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	sa,
		size_t	salen,
		uint8_t *	tid,
		size_t	tid_len,
		const lws_dht_hash_t *	infohash,
		uint8_t *	token,
		size_t	token_len,
		const uint8_t *	sha256,
		int	confirm )

#include <lws-dht.h>

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_send_ack()

LWS_VISIBLE LWS_EXTERN int lws_dht_send_ack	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	sa,
		size_t	salen,
		const uint8_t *	tid,
		size_t	tid_len )

#include <lws-dht.h>

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_send_notify()

LWS_VISIBLE LWS_EXTERN int lws_dht_send_notify	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	sa,
		size_t	salen,
		const uint8_t *	tid,
		size_t	tid_len,
		const lws_dht_hash_t *	infohash,
		const uint8_t *	sha256,
		const uint8_t *	payload,
		size_t	payload_len )

#include <lws-dht.h>

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_msg_parse()

LWS_VISIBLE LWS_EXTERN int lws_dht_msg_parse	(	const char *	in,
		size_t	len,
		struct lws_dht_msg *	out )

#include <lws-dht.h>

lws_dht_msg_parse() - Parse a raw DHT message

Parameters

in	raw message buffer
len	length of raw message
out	struct to populate with parsed data

Safe parsing of DHT command messages. The hash token must be 2 - 128 lowercase hex chars, otherwise the message is rejected.

Returns

0 on success, non-zero on error

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_valid_domain_name()

LWS_VISIBLE LWS_EXTERN int lws_dht_valid_domain_name

(

const char *

domain

)

#include <lws-dht.h>

lws_dht_valid_domain_name() - Check a domain string is a safe DNS name

Parameters

domain

NUL-terminated domain string

F-052: domain strings arriving on DHT NOTIFY datagrams are later composed into filesystem paths (zone cache paths, lws_dir walks), so they must be restricted to presentation-format DNS names: 1 - 253 chars of [A-Za-z0-9._-] split into non-empty labels of at most 63 chars, with an optional single trailing root dot. Anything else (path separators, "..", empty labels, junk bytes) is refused.

Returns

1 if the name is safe, 0 otherwise

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_msg_gen()

LWS_VISIBLE LWS_EXTERN int lws_dht_msg_gen	(	char *	out,
		size_t	len,
		const char *	verb,
		const char *	hash,
		unsigned long long	offset,
		unsigned long long	len_val )

#include <lws-dht.h>

lws_dht_msg_gen() - Generate a raw DHT message

Parameters

out	buffer to write message to
verb	e.g. "PUT", "GET", "REPLICATE"
hash	the hex SHA1 associated
offset	the byte offset
len_val	the length val

Generate a complete DHT payload with a space separated verb schema.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_register_verbs()

LWS_VISIBLE LWS_EXTERN int lws_dht_register_verbs	(	struct lws_dht_ctx *	ctx,
		const char **	verbs,
		int	count,
		const struct lws_protocols *	protocol )

#include <lws-dht.h>

lws_dht_register_verbs() - Register custom verb handlers

Parameters

ctx	DHT context
verbs	array of verb string names
count	number of verbs in array
protocol	the unified protocol handler owning these verbs

Returns

0 on success, non-zero on error

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_notify_subscribers()

LWS_VISIBLE LWS_EXTERN int lws_dht_notify_subscribers	(	struct lws_dht_ctx *	ctx,
		const lws_dht_hash_t *	hash,
		const uint8_t *	sha256,
		const uint8_t *	payload,
		size_t	payload_len )

#include <lws-dht.h>

lws_dht_notify_subscribers() - Notify subscribers of a hash change

Parameters

ctx	DHT context
hash	the hash that changed
sha256	the new sha256 of the content

Returns

number of subscribers notified, or negative on error

lws_dht_create()

LWS_VISIBLE LWS_EXTERN struct lws_dht_ctx * lws_dht_create

(

const lws_dht_info_t *

info

)

#include <lws-dht.h>

lws_dht_create() - Create a DHT context

Parameters

info	initialization parameters

Returns

pointer to DHT context or NULL on failure.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_closure()

LWS_VISIBLE LWS_EXTERN void * lws_dht_get_closure

(

struct lws_dht_ctx *

ctx

)

#include <lws-dht.h>

lws_dht_get_closure() - Get the user closure pointer

Parameters

ctx	DHT context

Returns

the closure pointer

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_myid()

LWS_VISIBLE LWS_EXTERN const lws_dht_hash_t * lws_dht_get_myid

(

struct lws_dht_ctx *

ctx

)

#include <lws-dht.h>

lws_dht_get_myid() - Get the local node's DHT ID hash

Parameters

ctx	DHT context

Returns

the local node's ID hash

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_destroy()

LWS_VISIBLE LWS_EXTERN void lws_dht_destroy

(

struct lws_dht_ctx **

pctx

)

#include <lws-dht.h>

lws_dht_destroy() - Destroy a DHT context

Parameters

pctx	pointer to the DHT context pointer to destroy

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_by_name()

LWS_VISIBLE LWS_EXTERN struct lws_dht_ctx * lws_dht_get_by_name	(	struct lws_vhost *	vhost,
		const char *	name )

#include <lws-dht.h>

lws_dht_get_by_name() - Get a specific DHT context by name

Parameters

vhost	vhost the DHT is bound to
name	name to match against

Returns

pointer to DHT context or NULL on failure.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_insert_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_insert_node	(	struct lws_dht_ctx *	ctx,
		const lws_dht_hash_t *	id,
		struct sockaddr *	sa,
		size_t	salen )

#include <lws-dht.h>

lws_dht_insert_node() - Manually insert a node into the DHT

Parameters

ctx	DHT context
id	ID of the node
sa	sockaddr of the node
salen	length of sockaddr

Returns

1 if successful, 0 if it already exists, or -1 on error.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_ping_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_ping_node	(	struct lws_dht_ctx *	ctx,
		struct sockaddr *	sa,
		size_t	salen )

#include <lws-dht.h>

lws_dht_ping_node() - Ping a node to verify it is alive

Parameters

ctx	DHT context
sa	sockaddr of the node
salen	length of sockaddr

Returns

number of bytes sent on success, or -1 on error.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_test_external_ips()

LWS_VISIBLE LWS_EXTERN void lws_dht_test_external_ips

(

struct lws_dht_ctx *

ctx

)

#include <lws-dht.h>

lws_dht_test_external_ips() - actively trigger IP verification probes to routing table

Parameters

ctx	the dht context

lws_dht_send_data()

LWS_VISIBLE LWS_EXTERN int lws_dht_send_data	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	dest,
		const void *	data,
		size_t	len )

#include <lws-dht.h>

lws_dht_send_data() - send a message to a peer reliably

Parameters

ctx	the dht context
dest	the peer's address
data	the message
len	its length

The message is given to the reliable transport for the peer, which keeps it until the peer acknowledges it. How much it keeps for one peer is bounded, so a peer that doesn't acknowledge, or a sender that outruns it, gets LWS_DHT_SEND_BUSY: the caller must keep the message, and send it again on LWS_DHT_EVENT_WRITEABLE for that peer. A caller that sends only replies to the peer's requests may instead drop it, if the peer asks again when its request goes unanswered.

Returns an enum lws_dht_send_result.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_send_data_at()

LWS_VISIBLE LWS_EXTERN int lws_dht_send_data_at	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	dest,
		uint64_t	offset,
		const void *	data,
		size_t	len )

#include <lws-dht.h>

lws_dht_send_data_at() - send a message at a stream offset to a peer

Parameters

ctx	the dht context
dest	the peer's address
offset	the offset in the stream to the peer to send it at
data	the message
len	its length

As lws_dht_send_data(), at a given offset.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_ts()

LWS_VISIBLE LWS_EXTERN struct lws_transport_sequencer * lws_dht_get_ts	(	struct lws_dht_ctx *	ctx,
		const struct sockaddr *	dest,
		size_t	salen,
		int	create )

#include <lws-dht.h>

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_search()

LWS_VISIBLE LWS_EXTERN int lws_dht_search	(	struct lws_dht_ctx *	ctx,
		const lws_dht_hash_t *	id,
		int	port,
		int	af,
		lws_dht_callback_t *	callback,
		void *	closure )

#include <lws-dht.h>

lws_dht_search() - Perform an asynchronous search for a hash

Parameters

ctx	DHT context
id	hash to search for
port	port to search on
af	address family (AF_INET, AF_INET6, or 0 for both)
callback	search completion/result callback
closure	closure for callback

This performs an iterative, asynchronous search for the requested hash. If port is non-zero, it also announces our availability for this hash.

Results (peers/values) are delivered to the callback as they are found via LWS_DHT_EVENT_VALUES or LWS_DHT_EVENT_VALUES6 events.

The callback is also called with event LWS_DHT_EVENT_SEARCH_DONE (or LWS_DHT_EVENT_SEARCH_DONE6) when the search operation has exhausted all potential nodes or reached a timeout. A search completes at the latest five minutes after it was started, on the nodes that answered it by then.

Returns

1 if search started successfully, 0 if answered locally (callback still called), or -1 on error.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_nodes()

LWS_VISIBLE LWS_EXTERN int lws_dht_nodes	(	struct lws_dht_ctx *	ctx,
		int	af,
		int *	good_return,
		int *	dubious_return,
		int *	cached_return,
		int *	incoming_return )

#include <lws-dht.h>

lws_dht_nodes() - Get statistics about DHT nodes

Parameters

ctx	DHT context
af	address family (AF_INET, AF_INET6)
good_return	count of known good nodes
dubious_return	count of dubious nodes
cached_return	count of cached nodes
incoming_return	count of incoming nodes

Returns

total number of good + dubious nodes.

lws_dht_foreach_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_foreach_node	(	struct lws_dht_ctx *	ctx,
		int	af,
		lws_dht_node_cb_t	cb,
		void *	user )

#include <lws-dht.h>

lws_dht_foreach_node() - visit each node in a routing table

Parameters

ctx	DHT context
af	which table, AF_INET or AF_INET6
cb	called with each node, return nonzero to stop
user	passed to cb

Lets the application see, eg, why a node it expects to be good is not. The table must not be changed from cb.

Returns

how many nodes cb was called with.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_foreach_search_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_foreach_search_node	(	struct lws_dht_ctx *	ctx,
		const lws_dht_hash_t *	target,
		int	af,
		lws_dht_node_cb_t	cb,
		void *	user )

#include <lws-dht.h>

lws_dht_foreach_search_node() - visit the candidates of a search

Parameters

ctx	DHT context
target	the id the search is for, as given to lws_dht_search()
af	the search's address family, AF_INET or AF_INET6
cb	called with each candidate, return nonzero to stop
user	passed to cb

Visits the nodes a search is querying, or has queried, closest to target first, so the application can see where a lookup went. In the lws_dht_node_info_t, heard and replied are the seconds since the node answered this search (-1 if it has not), pinged is how many requests this search sent it that are unanswered, good is whether it answered this search, and bep42_ok is as for lws_dht_foreach_node(). The search must not be changed from cb.

Returns

how many candidates cb was called with, or -1 if there is no search for target in af.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_dump_tables()

LWS_VISIBLE LWS_EXTERN void lws_dht_dump_tables

(

struct lws_dht_ctx *

ctx

)

#include <lws-dht.h>

lws_dht_dump_tables() - Log the state of DHT routing tables

Parameters

ctx	DHT context

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_nodes()

LWS_VISIBLE LWS_EXTERN int lws_dht_get_nodes	(	struct lws_dht_ctx *	ctx,
		struct sockaddr_in *	sin,
		int *	num,
		struct sockaddr_in6 *	sin6,
		int *	num6 )

#include <lws-dht.h>

lws_dht_get_nodes() - Get a list of known nodes

Parameters

ctx	DHT context
sin	buffer for IPv4 nodes
num	in/out count for IPv4 nodes
sin6	buffer for IPv6 nodes
num6	in/out count for IPv6 nodes

Returns

total number of nodes filled (v4 + v6).

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_external_addr()

LWS_VISIBLE LWS_EXTERN int lws_dht_get_external_addr	(	struct lws_dht_ctx *	ctx,
		struct sockaddr_storage *	ss,
		size_t *	sslen )

#include <lws-dht.h>

lws_dht_get_external_addr() - Get our external IP and port as determined by STUN

Parameters

ctx	DHT context
ss	buffer for external address and port
sslen	length of buffer/written address

Returns

0 on success, or -1 if the address and port are not yet determined.

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_bep42_id()

LWS_VISIBLE LWS_EXTERN lws_dht_hash_t * lws_dht_bep42_id	(	struct lws_context *	cx,
		const struct sockaddr *	sa,
		uint8_t	rand,
		int	type,
		int	len )

#include <lws-dht.h>

lws_dht_bep42_id() - make a node id bound to an address (BEP42)

Parameters

cx	the lws context (its randomness is used)
sa	the node's public address (AF_INET or AF_INET6)
rand	the random byte that ends the id (BEP42's "r")
type	LWS_DHT_HASH_TYPE_... of the id to make
len	the id length in bytes for that type (20 for sha1)

BEP42 ties a node id to the node's IP: the first 21 bits are the CRC32C of the masked address with three bits of rand folded in, the last byte is rand, the rest is random. A peer can then check the id it is told against the address it hears it from, which is what stops one host choosing ids to fill a bucket. lws applies the rule to the first three and last byte of an id of any length.

Returns

a new id to free with lws_dht_hash_destroy(), or NULL

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_same_host()

LWS_VISIBLE LWS_EXTERN int lws_dht_same_host	(	const struct sockaddr *	a,
		const struct sockaddr *	b )

#include <lws-dht.h>

lws_dht_same_host() - are two addresses the same host, as the DHT counts

Parameters

a	one address
b	the other address

The DHT gives each source host its share of what it limits (request admission, routing table and search entries, storage, votes): a host is an IPv4 address or an IPv6 /64, whatever the port, since one machine can use any number of ports and any number of addresses in its prefix. Protocols running over the DHT should account to the same notion of a host.

Returns

1 if a and b are the same host, else 0

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_bep42_check()

LWS_VISIBLE LWS_EXTERN int lws_dht_bep42_check	(	const lws_dht_hash_t *	id,
		const struct sockaddr *	sa )

#include <lws-dht.h>

lws_dht_bep42_check() - does a node id conform to BEP42 for its address

Parameters

id	the node id the peer claims
sa	the address the claim came from

Returns

1 if the id's first 21 bits are the BEP42 derivation for sa and the id's last byte, 0 if not (or the family is unknown)

References LWS_EXTERN, and LWS_VISIBLE.

lws_dht_get_fallback_node()

LWS_VISIBLE LWS_EXTERN int lws_dht_get_fallback_node	(	struct lws_context *	cx,
		const char *	custom_path,
		char *	result,
		size_t	result_len )

#include <lws-dht.h>

lws_dht_get_fallback_node() - Retrieves a default DHT node from the system installation

Parameters

cx	lws_context to seed the randomizer
result	buffer to write the randomly chosen fallback node IP:port
result_len	size of the output buffer

Returns

0 on success, or -1 if the fallback file could not be read.

Variable Documentation

lws_dht_protocol

const struct lws_protocols lws_dht_protocol

extern

#include <lws-dht.h>