lws-dht.h

Go to the documentation of this file.

/*
 * Copyright (c) 2009-2011 by Juliusz Chroboczek
 * Copyright (c) 2026 Andy Green <andy@warmcat.com>
 *  Adaptation for lws, cleaning, modernization
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
 
#if !defined(__LWS_DHT_H__)
#define __LWS_DHT_H__
 
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <libwebsockets/lws-genhash.h>

 
struct lws_dht_ctx;
 
extern const struct lws_protocols lws_dht_protocol;

typedef struct lws_dht_hash {
        uint8_t                  type; /* LWS_DHT_HASH_TYPE_... */
        uint8_t                  len;
        uint8_t                  id[];
} lws_dht_hash_t;
 
enum {
        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 */
};
 
#define LWS_DHT_SHA1_HASH_LEN 20

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);

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);
 
struct lws_dht_msg {
        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;
};
 
typedef enum {
        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;
 
#define LWS_DHT_STAT_BUCKETS 48

struct lws_dht_stats {
        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_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);
 
struct lws_dht_verb_dispatch_args {
        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_VISIBLE LWS_EXTERN int
lws_dht_send_subscribe(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,
                       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_msg_parse(const char *in, size_t len, struct lws_dht_msg *out);

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);

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);
 
/* The maximum number of peers we store for a given hash. */
#define DHT_MAX_PEERS 2048
 
/* The maximum number of hashes we're willing to track. */
#define DHT_MAX_HASHES 16384
 
/* The maximum number of searches we keep data about. */
#define DHT_MAX_SEARCHES 1024
 
/* The time after which we consider a search to be expirable. */
#define DHT_SEARCH_EXPIRE_TIME (62 * 60)

typedef enum {
        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_t;
 

typedef struct lws_dht_info {
        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                          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;
} lws_dht_info_t;

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 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 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 int
lws_dht_get_fallback_node(struct lws_context *cx, const char *custom_path, char *result, size_t result_len);
 
#endif /* __LWS_DHT_H__ */