kubo/docs/changelogs/v0.18.md

Kubo changelog v0.18

v0.18.0

Overview

Below is an outline of all that is in this release, so you get a sense of all that's included.

• Overview
• 🔦 Highlights
  • DAG-JSON and DAG-CBOR Response Formats on Gateways
  • 🐎 Fast directory listings with DAG sizes
  • Content Routing
  • WebTransport enabled by default
    • WebTransport + QUIC on one single port
  • QUICv1 & WebTransport Config Migration
    • /quic Draft-29 early-deprecation
  • Provider Record Republish and Expiration
  • Improving libp2p resource management integration
• Changelog
• Contributors

🔦 Highlights

(DAG-)JSON and (DAG-)CBOR Response Formats on Gateways

Implemented IPIP-328 which adds support to DAG-JSON and DAG-CBOR, as well as their non-DAG variants, to the gateway. Now, CIDs that encode JSON, CBOR, DAG-JSON and DAG-CBOR objects can be retrieved, and traversed thanks to the special meaning of CBOR Tag 42.

HTTP clients can request JSON, CBOR, DAG-JSON, and DAG-CBOR responses by either passing the query parameter ?format or setting the Accept HTTP header to the following values:

• JSON: ?format=json, or Accept: application/json
• CBOR: ?format=cbor, or Accept: application/cbor
• DAG-JSON: ?format=dag-json, or Accept: application/vnd.ipld.dag-json
• DAG-JSON: ?format=dag-cbor, or Accept: application/vnd.ipld.dag-cbor

$ export DIR_CID=bafybeigccimv3zqm5g4jt363faybagywkvqbrismoquogimy7kvz2sj7sq
$ curl -H "Accept: application/vnd.ipld.dag-json" "http://127.0.0.1:8080/ipfs/$DIR_CID" | jq
$ curl "http://127.0.0.1:8080/ipfs/$DIR_CID?format=dag-json" | jq
{
  "Data": {
    "/": {
      "bytes": "CAE"
    }
  },
  "Links": [
    {
      "Hash": {
        "/": "Qmc3zqKcwzbbvw3MQm3hXdg8BQoFjGdZiGdAfXAyAGGdLi"
      },
      "Name": "1 - Barrel - Part 1 - alt.txt",
      "Tsize": 21
    },
    {
      "Hash": {
        "/": "QmdMxMx29KVYhHnaCc1icWYxQqXwUNCae6t1wS2NqruiHd"
      },
      "Name": "1 - Barrel - Part 1 - transcript.txt",
      "Tsize": 195
    },
    {
      "Hash": {
        "/": "QmawceGscqN4o8Y8Fv26UUmB454kn2bnkXV5tEQYc4jBd6"
      },
      "Name": "1 - Barrel - Part 1.png",
      "Tsize": 24862
    }
  ]
}

🐎 Fast directory listings with DAG sizes

Fast listings are now enabled for all UnixFS directories: big and small. There is no linear slowdown caused by reading size metadata from child nodes, and the size of DAG representing child items is always present.

As an example, the CID bafybeiggvykl7skb2ndlmacg2k5modvudocffxjesexlod2pfvg5yhwrqm represents UnixFS directory with over 10k (10100) of files. Listing big directories was fast since Kubo 0.13, but in this release it will also include the size column.

Content Routing

Content routing is the process of discovering which peers provide a piece of content. Kubo has traditionally only supported libp2p's implementation of Kademlia DHT for content routing.

Kubo can now bridge networks by including support for the delegated routing HTTP API. Users can compose content routers using the Routing.Routers config, to pick content routers with different tradeoffs than a Kademlia DHT (for example, high-performance and high-capacity centralized endpoints, dedicated Kademlia DHT nodes, routers with unique provider records, privacy-focused content routers, etc.).

One example is InterPlanetary Network Indexers, which are HTTP endpoints that cache records from both the IPFS network and other sources such as web3.storage and Filecoin. This improves not only content availability by enabling Kubo to transparently fetch content directly from Filecoin storage providers, but also improves IPFS content routing latency by an order of magnitude and decreases resource consumption. Note: it's possible to retrieve content stored by Filecoin Storage Providers (SPs) from Kubo if the SPs service Bitswap requests. As of this release, some SPs are advertising Bitswap. You can follow the roadmap progress for IPNIs and Bitswap in SPs here.

In this release, the default content router is changed from dht to auto. The auto router includes the IPFS DHT in addition to the cid.contact IPNI instance. In future releases, we plan to expand the functionality of auto to encompass automatic discovery of content routers, which will improve performance and content availability (for example, see IPIP-342).

Previous behavior can be restored by setting Routing.Type to dht.

Alternative routing rules, including alternative IPNI endpoints, can be configured in Routing.Routers after setting Routing.Type to custom.

Learn more in Routing docs.

WebTransport enabled by default

WebTransport is a new libp2p transport that has been introduced in v0.16 that is based on top of QUIC and HTTP3.

This allows browsers to contact Kubo nodes, so now instead of just serving requests for other system level applicative nodes, you can also serve requests directly to a browser. For the full story see connectivity.libp2p.io.

WebTransport + QUIC on one single port

The new feature that allows us to ship WebTransport by default is that go-libp2p now supports running WebTransport and QUIC transports on the same QUIC listener.

To use this feature, you just have to register two listen address on the same /ipX/.../udp/XXX prefix.

QUICv1 & WebTransport Config Migration

Go-libp2p now differentiate the first version of QUIC we implemented (and were using until then), Draft-29, and the ratified protocol in RFC9000, QUICv1. This manifest as two different multiaddr components /quic (old Draft-29) and /quic-v1.

Even tho Draft-29 and QUICv1 are similar they are not fully inter-compatible, go-libp2p do supports listening with both versions on one single listener.

/webtransport now also need to be prefixed by a /quic-v1 instead of /quic component. This has no protocol change, WebTransport only supports QUICv1 and were running on QUICv1 already.

To support QUICv1 and WebTransport by default we run a new migration (n°13) which automatically add entries in addresses related fields in the config:

• Replace all /quic/webtransport to /quic-v1/webtransport.
• For all /quic listener, keep the Draft-29 listener, and on the same ip and port, add /quic-v1 and /quic-v1/webtransport listeners.

/quic (Draft-29) early-deprecation

We plan to remove support for QUIC Draft-29 in the mid to long term future.

You must not use /quic for new deployements and use /quic-v1 instead.

Provider Record Republish and Expiration

Default Reprovider.Interval changed from 12h to 22h to match new defaults for the Provider Record Expiration (48h) in go-libp2p-kad-dht v0.20.0.

Rationale for increasing this can be found in RFM 17: Provider Record Livenes Report, kubo#9326, and the upstream DHT specifications at libp2p/specs#451.

Learn more: Reprovider config

Improving libp2p resource management integration

To help protect nodes from DoS (resource exhaustion) and eclipse attacks, Kubo enabled the go-libp2p Network Resource Manager by default in Kubo 0.17.

Introducing limits like this by default after the fact is tricky, and various improvements have been made to improve the UX including:

1. Dedicated docs concerning the resource manager integration. This is a great place to go to learn more or get your FAQs answered.
2. Increasing the default limits for the resource manager.
3. Enabling the Swarm.ConnMgr by default and reducing it thresholds so it can intelligently prune connections in many cases before the indiscriminate resource manager kicks in.
4. Adjusted log messages and levels to make clear that the resource manager is likely doing your node a favor by bounding resources.
5. Other miscellaneous config and command bugs reported by users.

Changelog

Contributors