🪢 caskadht

caskadht, pronounced "Cascade-DHT", is a service that:

• exposes:
  • GET /routing/v1/providers/<cid> compatible with IPFS HTTP delegated routing, and
  • GET /multihash/<multihash> compatible with IPNI HTTP query API
• cascades lookup requests over the IPFS Kademlia DHT,
• uses the accelerated DHT client when possible, and
• steams the results back over ndjson whenever the request Accept header permits it, or non-streaming JSON otherwise.

Install

To install caskadht CLI directly via Golang, run:

$ go install github.com/ipni/caskadht/cmd/caskadht@latest

Usage

$ caskadht 
Usage of caskadht:
  -httpListenAddr string
        The caskadht HTTP server listen address in address:port format. (default "0.0.0.0:40080")
  -httpResponsePreferJson
        Whether to prefer responding with JSON instead of NDJSON when Accept header is set to "*/*".
  -ipniCascadeLabel string
        The IPNI cascade label associated to this instance. (default "ipfs-dht")
  -ipniRequireQueryParam
        Weather to require IPNI "cascade" query parameter with matching label in order to respond to HTTP lookup requests. Not required by default.
  -libp2pIdentityPath string
        The path to the marshalled libp2p host identity. If unspecified a random identity is generated.
  -libp2pListenAddrs string
        The comma separated libp2p host listen multiaddrs. If unspecified the default listen multiaddrs are used at ephemeral port.
  -logLevel string
        The logging level. Only applied if GOLOG_LOG_LEVEL environment variable is unset. (default "info")
  -useAcceleratedDHT
        Weather to use accelerated DHT client when possible. (default true)

Run Server Locally

To run the caskadht HTTP server locally, execute:

$ go run cmd/caskadht/main.go

The above command starts the HTTP API exposed on default listen address: http://localhost:40080. You can then start looking up multihashes, which would cascade onto the DHT.

To shutdown the server, interrupt the terminal by pressing Ctrl + C

Example IPNI ndjson response:

$ curl http://localhost:40080/multihash/QmfQJymEUXsGNzHMmpGYmUcFiAtGw2ia97EXNDVDZbZjgm -v --max-time 1
*   Trying 127.0.0.1:40080...
* Connected to localhost (127.0.0.1) port 40080 (#0)
> GET /multihash/QmfQJymEUXsGNzHMmpGYmUcFiAtGw2ia97EXNDVDZbZjgm HTTP/1.1
> Host: localhost:40080
> User-Agent: curl/7.86.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Connection: Keep-Alive
< Content-Type: application/x-ndjson
< X-Content-Type-Options: nosniff
< Date: Sat, 28 Jan 2023 18:06:44 GMT
< Transfer-Encoding: chunked
< 
{"ContextID":"aXBmcy1kaHQtY2FzY2FkZQ==","Metadata":"gBI=","Provider":{"ID":"12D3KooWSnniGsyAF663gvHdqhyfJMCjWJv54cGSzcPiEMAfanvU","Addrs":["/ip6/2604:1380:45f1:8400::1/tcp/4002/ws","/ip4/145.40.89.195/tcp/4002/ws","/ip6/2604:1380:45f1:8400::1/tcp/4001","/ip4/145.40.89.195/tcp/4001"]}}
{"ContextID":"aXBmcy1kaHQtY2FzY2FkZQ==","Metadata":"gBI=","Provider":{"ID":"12D3KooWEDMw7oRqQkdCJbyeqS5mUmWGwTp8JJ2tjCzTkHboF6wK","Addrs":["/ip6/2604:1380:45e1:2700::3/tcp/4001","/ip6/2604:1380:45e1:2700::3/tcp/4002/ws","/ip4/139.178.68.91/tcp/4001","/ip4/139.178.68.91/tcp/4002/ws"]}}
{"ContextID":"aXBmcy1kaHQtY2FzY2FkZQ==","Metadata":"gBI=","Provider":{"ID":"12D3KooWRgXWwnZQJgdW1GHW7hJ5UvZ8MLp7HBCSWS596PypAs8M","Addrs":["/ip4/147.75.49.91/tcp/4002/ws","/ip6/2604:1380:45e1:2700::b/tcp/4001","/ip6/2604:1380:45e1:2700::b/tcp/4002/ws","/ip4/147.75.49.91/tcp/4001"]}}
* Operation timed out after 1005 milliseconds with 1890 bytes received
* Closing connection 0
curl: (28) Operation timed out after 1005 milliseconds with 1890 bytes received

Example IPFS Delegated Routing ndjson Response

$ curl  http://localhost:40080/routing/v1/providers/QmfQJymEUXsGNzHMmpGYmUcFiAtGw2ia97EXNDVDZbZjgm -v --max-time 1
*   Trying 127.0.0.1:40080...
* Connected to localhost (127.0.0.1) port 40080 (#0)
> GET /routing/v1/providers/QmfQJymEUXsGNzHMmpGYmUcFiAtGw2ia97EXNDVDZbZjgm HTTP/1.1
> Host: localhost:40080
> User-Agent: curl/7.86.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Connection: Keep-Alive
< Content-Type: application/x-ndjson
< X-Content-Type-Options: nosniff
< Date: Sat, 28 Jan 2023 18:07:40 GMT
< Transfer-Encoding: chunked
< 
{"Protocol":"transport-bitswap","Schema":"bitswap","ID":"12D3KooWHVXoJnv2ifmr9K6LWwJPXxkfvzZRHzjiTZMvybeTnwPy","Addrs":["/ip4/145.40.89.101/tcp/4001","/ip4/145.40.89.101/tcp/4002/ws","/ip4/145.40.89.101/udp/4001/quic","/ip6/2604:1380:45f1:d800::1/tcp/4001","/ip6/2604:1380:45f1:d800::1/tcp/4002/ws","/ip6/2604:1380:45f1:d800::1/udp/4001/quic"]}
{"Protocol":"transport-bitswap","Schema":"bitswap","ID":"12D3KooWDpp7U7W9Q8feMZPPEpPP5FKXTUakLgnVLbavfjb9mzrT","Addrs":["/ip4/147.75.80.75/tcp/4001","/ip4/147.75.80.75/tcp/4002/ws","/ip4/147.75.80.75/udp/4001/quic","/ip6/2604:1380:4601:f600::5/tcp/4001","/ip6/2604:1380:4601:f600::5/tcp/4002/ws","/ip6/2604:1380:4601:f600::5/udp/4001/quic"]}
{"Protocol":"transport-bitswap","Schema":"bitswap","ID":"12D3KooWCrBiagtZMzpZePCr1tfBbrZTh4BRQf7JurRqNMRi8YHF","Addrs":["/ip4/147.75.87.65/tcp/4001","/ip4/147.75.87.65/tcp/4002/ws","/ip4/147.75.87.65/udp/4001/quic","/ip6/2604:1380:4601:f600::1/tcp/4001","/ip6/2604:1380:4601:f600::1/tcp/4002/ws","/ip6/2604:1380:4601:f600::1/udp/4001/quic"]}
{"Protocol":"transport-bitswap","Schema":"bitswap","ID":"12D3KooWRNijznEQoXrxBeNLb2TqbSFm8gG8jKtfEsbC1C9nPqce","Addrs":["/ip4/147.75.87.211/tcp/4001","/ip4/147.75.87.211/tcp/4002/ws","/ip4/147.75.87.211/udp/4001/quic","/ip6/2604:1380:4601:f600::3/tcp/4001","/ip6/2604:1380:4601:f600::3/tcp/4002/ws","/ip6/2604:1380:4601:f600::3/udp/4001/quic"]}
* Operation timed out after 1001 milliseconds with 1378 bytes received
* Closing connection 0
curl: (28) Operation timed out after 1001 milliseconds with 1378 bytes received

License

SPDX-License-Identifier: Apache-2.0 OR MIT