@helia/verified-fetch 7.1.0 → 7.2.1

package/README.md

@@ -805,6 +805,82 @@ To add your own plugin:
 
 For a detailed explanation of the pipeline, please refer to the discussion in [Issue #167](https://github.com/ipfs/helia-verified-fetch/issues/167).
 
+### Server-Timing
+
+Detailed timing is found in the [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Server-Timing)
+HTTP header that is returned with every response when a resource is requested
+with the `withServerTiming` init option set to `true`.
+
+The `dur` field is in milliseconds, so `dur=100` took 100ms. It is possible
+to measure in greater precision, but given these are network operations it's
+better to limit the precision and have a smaller header size, since
+downloading the headers impacts the time to first byte.
+
+To prevent the header value growing too large, PeerIDs/CIDs are truncated to
+their first 10 characters and common strings are abbreviated.
+
+The values you may expect to see are described in the following table. Note
+that not all of them may be present in a given response.
+
+Router, block broker and transport abbreviations used in the `desc` fields
+follow.
+
+| Timing metric | Elaboration     | Detail                                                                                                                                                                                                | Example                                        |
+| ------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| d             | DNSLink.resolve | Resolving a DNSLink to an IPFS path or IPNS name                                                                                                                                                      | `d;dur=0.200`                                  |
+| i             | IPFS.resolve    | Resolving a CID + path to a CID                                                                                                                                                                       | `i;dur=0.200`                                  |
+| n             | IPNS.resolve    | Resolving an IPNS name to an IPFS path                                                                                                                                                                | `n;dur=0.200`                                  |
+| p             | Provider        | A provider was found. The `desc` field contains the routing system that found the provider and the first 10 characters of the PeerId                                                                  | `p;dur=0.000;desc="h,bagqbeaawn"`              |
+| f             | Find Providers  | The total duration of the routing systems Find Providers operation. The `desc` field contains the routing system and how many providers were found                                                    | `f;dur=2.000;desc="h,4"`                       |
+| c             | Connect         | How long it took to connect to a provider. The `desc` field contains the type of provider, the first 10 characters of their PeerId and the transport used                                             | `b;dur=0.000;desc="t,bagqbeaa7n,bafybeigoc,t"` |
+| b             | Block           | How long it took to retrieve a block from the provider once connected. The `desc` field contains the type of provider, the first 10 characters of their PeerId and the first 10 characters of the CID | `b;dur=0.000;desc="t,bagqbeaa7n,bafybeigoc"`   |
+
+A full header might look like:
+
+```
+i;dur=0,p;dur=0;desc="h,bagqbeaawn",p;dur=0;desc="h,bagqbeaawn",p;dur=1;desc="h,bagqbeaa7n",p;dur=1;desc="h,bagqbeaa7n",f;dur=1;desc="h,4",f;dur=1;desc="h,4",f;dur=144;desc="l,0",f;dur=144;desc="l,0",c;dur=206;desc="t,bagqbeaa7n,h",b;dur=1;desc="t,bagqbeaa7n,bafybeigoc"
+```
+
+Here resolving a CID to a CID+path took less than a millisecond (e.g. a bare
+CID was requested).
+
+Two HTTP Gateway providers were found in the routing (`bagqbeaawn` and
+`bagqbeaa7n`). They are found twice because two block brokers are configured
+(bitswap and trustless-gateway) which both make a routing request (results
+are cached internally so the duration to find them the second time differs).
+
+It took 206ms to connect to `bagqbeaa7n` over HTTP, and 1s to retrieve the
+block for the CID `bafybeigo` from the Trustless Gateway `bagqbeaa7n`.
+
+All PeerIDs and CIDs above are truncated to 10 characters.
+
+#### Router abbreviations
+
+| Router | Elaboration           |
+| ------ | --------------------- |
+| h      | HTTP Gateway          |
+| l      | Libp2p (e.g. Kad-DHT) |
+
+#### Block broker abbreviations
+
+| Block Broker | Elaboration       |
+| ------------ | ----------------- |
+| t            | Trustless Gateway |
+| b            | Bitswap           |
+
+#### Transport abbreviations
+
+| Transport | Elaboration   |
+| --------- | ------------- |
+| t         | TCP           |
+| h         | HTTP          |
+| w         | WebSockets    |
+| r         | WebRTC        |
+| d         | WebRTC-Direct |
+| q         | QUIC          |
+| b         | WebTransport  |
+| u         | Unknown       |
+
 # Install
 
 ```console