feat: add server timing to responses (#164)

* feat: add server timing to responses

* chore: remove unique id on stream-and-chunk

* fix: more timings and add timing header before err

* fix: serverTiming is easy to add to functions

* test: add server timing tests

* fix: serverTiming duration testing is robust across platforms

* fix: server timing headers are not included by default

* docs: explain server timing header capabilities

* docs: fix server timing docs and generate new readme

* chore: pr suggestion

Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>

* feat: ipns+dnslink server timing, renames & refactoring

* chore: remove unnecessary null coalescing operator

---------

Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com>

Author: SgtPooki

packages/verified-fetch/README.md

@@ -635,6 +635,14 @@ Some known header specifications:
 - <https://specs.ipfs.tech/http-gateways/trustless-gateway/#response-headers>
 - <https://specs.ipfs.tech/http-gateways/subdomain-gateway/#response-headers>
 
+#### Server Timing headers
+
+By default, we do not include [Server Timing](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/Server_timing) headers in responses. If you want to include them, you can pass an
+`withServerTiming` option to the `createVerifiedFetch` function to include them in all future responses. You can
+also pass the `withServerTiming` option to each fetch call to include them only for that specific response.
+
+See PR where this was added, <https://github.com/ipfs/helia-verified-fetch/pull/164>, for more information.
+
 ### Possible Scenarios that could cause confusion
 
 #### Attempting to fetch the CID for content that does not make sense

packages/verified-fetch/src/index.ts

@@ -604,6 +604,14 @@
  * * https://specs.ipfs.tech/http-gateways/trustless-gateway/#response-headers
  * * https://specs.ipfs.tech/http-gateways/subdomain-gateway/#response-headers
  *
+ * #### Server Timing headers
+ *
+ * By default, we do not include [Server Timing](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/Server_timing) headers in responses. If you want to include them, you can pass an
+ * `withServerTiming` option to the `createVerifiedFetch` function to include them in all future responses. You can
+ * also pass the `withServerTiming` option to each fetch call to include them only for that specific response.
+ *
+ * See PR where this was added, https://github.com/ipfs/helia-verified-fetch/pull/164, for more information.
+ *
  * ### Possible Scenarios that could cause confusion
  *
  * #### Attempting to fetch the CID for content that does not make sense
@@ -750,6 +758,14 @@ export interface CreateVerifiedFetchOptions {
    * @default 60000
    */
   sessionTTLms?: number
+
+  /**
+   * Whether to include server-timing headers in responses. This option can be overridden on a per-request basis.
+   *
+   * @default false
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing
+   */
+  withServerTiming?: boolean
 }
 
 export type { ContentTypeParser } from './types.js'
@@ -817,6 +833,14 @@ export interface VerifiedFetchInit extends RequestInit, ProgressOptions<BubbledP
    * @default false
    */
   allowInsecure?: boolean
+
+  /**
+   * Whether to include server-timing headers in the response for an individual request.
+   *
+   * @default false
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing
+   */
+  withServerTiming?: boolean
 }
 
 /**

packages/verified-fetch/src/types.ts

@@ -29,6 +29,11 @@ export interface FetchHandlerFunctionArg {
    * The originally requested resource
    */
   resource: string
+
+  /**
+   * Whether to include server-timing headers in the response.
+   */
+  withServerTiming: boolean
 }
 
 /**

packages/verified-fetch/src/utils/parse-resource.ts

@@ -11,16 +11,16 @@ export interface ParseResourceComponents {
 }
 
 export interface ParseResourceOptions extends ParseUrlStringOptions {
-
+  withServerTiming?: boolean
 }
 /**
  * Handles the different use cases for the `resource` argument.
  * The resource can represent an IPFS path, IPNS path, or CID.
  * If the resource represents an IPNS path, we need to resolve it to a CID.
  */
-export async function parseResource (resource: Resource, { ipns, logger }: ParseResourceComponents, options?: ParseResourceOptions): Promise<ParsedUrlStringResults> {
+export async function parseResource (resource: Resource, { ipns, logger }: ParseResourceComponents, { withServerTiming = false, ...options }: ParseResourceOptions = { withServerTiming: false }): Promise<ParsedUrlStringResults> {
   if (typeof resource === 'string') {
-    return parseUrlString({ urlString: resource, ipns, logger }, options)
+    return parseUrlString({ urlString: resource, ipns, logger, withServerTiming }, options)
   }
 
   const cid = CID.asCID(resource)
@@ -33,7 +33,8 @@ export async function parseResource (resource: Resource, { ipns, logger }: Parse
       path: '',
       query: {},
       ipfsPath: `/ipfs/${cid.toString()}`,
-      ttl: 29030400 // 1 year for ipfs content
+      ttl: 29030400, // 1 year for ipfs content
+      serverTimings: []
     } satisfies ParsedUrlStringResults
   }
 

packages/verified-fetch/src/utils/parse-url-string.ts

@@ -1,5 +1,6 @@
 import { CID } from 'multiformats/cid'
 import { getPeerIdFromString } from './get-peer-id-from-string.js'
+import { serverTiming, type ServerTimingResult } from './server-timing.js'
 import { TLRU } from './tlru.js'
 import type { RequestFormatShorthand } from '../types.js'
 import type { DNSLinkResolveResult, IPNS, IPNSResolveResult, IPNSRoutingEvents, ResolveDNSLinkProgressEvents, ResolveProgressEvents, ResolveResult } from '@helia/ipns'
@@ -12,6 +13,7 @@ export interface ParseUrlStringInput {
   urlString: string
   ipns: IPNS
   logger: ComponentLogger
+  withServerTiming?: boolean
 }
 export interface ParseUrlStringOptions extends ProgressOptions<ResolveProgressEvents | IPNSRoutingEvents | ResolveDNSLinkProgressEvents>, AbortOptions {
 
@@ -23,7 +25,7 @@ export interface ParsedUrlQuery extends Record<string, string | unknown> {
   filename?: string
 }
 
-interface ParsedUrlStringResultsBase extends ResolveResult {
+export interface ParsedUrlStringResults extends ResolveResult {
   protocol: 'ipfs' | 'ipns'
   query: ParsedUrlQuery
 
@@ -41,9 +43,12 @@ interface ParsedUrlStringResultsBase extends ResolveResult {
    * seconds as a number
    */
   ttl?: number
-}
 
-export type ParsedUrlStringResults = ParsedUrlStringResultsBase
+  /**
+   * serverTiming items
+   */
+  serverTimings: Array<ServerTimingResult<any>>
+}
 
 const URL_REGEX = /^(?<protocol>ip[fn]s):\/\/(?<cidOrPeerIdOrDnsLink>[^/?]+)\/?(?<path>[^?]*)\??(?<queryString>.*)$/
 const PATH_REGEX = /^\/(?<protocol>ip[fn]s)\/(?<cidOrPeerIdOrDnsLink>[^/?]+)\/?(?<path>[^?]*)\??(?<queryString>.*)$/
@@ -145,14 +150,15 @@ function dnsLinkLabelDecoder (linkLabel: string): string {
  * @todo we need to break out each step of this function (cid parsing, ipns resolving, dnslink resolving) into separate functions and then remove the eslint-disable comment
  */
 // eslint-disable-next-line complexity
-export async function parseUrlString ({ urlString, ipns, logger }: ParseUrlStringInput, options?: ParseUrlStringOptions): Promise<ParsedUrlStringResults> {
+export async function parseUrlString ({ urlString, ipns, logger, withServerTiming = false }: ParseUrlStringInput, options?: ParseUrlStringOptions): Promise<ParsedUrlStringResults> {
   const log = logger.forComponent('helia:verified-fetch:parse-url-string')
   const { protocol, cidOrPeerIdOrDnsLink, path: urlPath, queryString } = matchURLString(urlString)
 
   let cid: CID | undefined
   let resolvedPath: string | undefined
   const errors: Error[] = []
   let resolveResult: IPNSResolveResult | DNSLinkResolveResult | undefined
+  const serverTimings: Array<ServerTimingResult<any>> = []
 
   if (protocol === 'ipfs') {
     try {
@@ -182,7 +188,19 @@ export async function parseUrlString ({ urlString, ipns, logger }: ParseUrlStrin
         if (peerId.publicKey == null) {
           throw new TypeError('cidOrPeerIdOrDnsLink contains no public key')
         }
-        resolveResult = await ipns.resolve(peerId.publicKey, options)
+
+        if (withServerTiming) {
+          const resolveResultWithServerTiming = await serverTiming('ipns.resolve', `Resolve IPNS name ${cidOrPeerIdOrDnsLink}`, ipns.resolve.bind(null, peerId.publicKey, options))
+          serverTimings.push(resolveResultWithServerTiming)
+
+          // eslint-disable-next-line max-depth
+          if (resolveResultWithServerTiming.error != null) {
+            throw resolveResultWithServerTiming.error
+          }
+          resolveResult = resolveResultWithServerTiming.result
+        } else {
+          resolveResult = await ipns.resolve(peerId.publicKey, options)
+        }
         cid = resolveResult?.cid
         resolvedPath = resolveResult?.path
         log.trace('resolved %s to %c', cidOrPeerIdOrDnsLink, cid)
@@ -207,7 +225,19 @@ export async function parseUrlString ({ urlString, ipns, logger }: ParseUrlStrin
         log.trace('Attempting to resolve DNSLink for %s', decodedDnsLinkLabel)
 
         try {
-          resolveResult = await ipns.resolveDNSLink(decodedDnsLinkLabel, options)
+          // eslint-disable-next-line max-depth
+          if (withServerTiming) {
+            const resolveResultWithServerTiming = await serverTiming('ipns.resolveDNSLink', `Resolve DNSLink ${decodedDnsLinkLabel}`, ipns.resolveDNSLink.bind(ipns, decodedDnsLinkLabel, options))
+            serverTimings.push(resolveResultWithServerTiming)
+            // eslint-disable-next-line max-depth
+            if (resolveResultWithServerTiming.error != null) {
+              throw resolveResultWithServerTiming.error
+            }
+            resolveResult = resolveResultWithServerTiming.result
+          } else {
+            resolveResult = await ipns.resolveDNSLink(decodedDnsLinkLabel, options)
+          }
+
           cid = resolveResult?.cid
           resolvedPath = resolveResult?.path
           log.trace('resolved %s to %c', decodedDnsLinkLabel, cid)
@@ -263,7 +293,8 @@ export async function parseUrlString ({ urlString, ipns, logger }: ParseUrlStrin
     path: joinPaths(resolvedPath, urlPath ?? ''),
     query,
     ttl,
-    ipfsPath: `/${protocol}/${cidOrPeerIdOrDnsLink}${urlPath != null && urlPath !== '' ? `/${urlPath}` : ''}`
+    ipfsPath: `/${protocol}/${cidOrPeerIdOrDnsLink}${urlPath != null && urlPath !== '' ? `/${urlPath}` : ''}`,
+    serverTimings
   } satisfies ParsedUrlStringResults
 }
 

packages/verified-fetch/src/utils/server-timing.ts

@@ -0,0 +1,37 @@
+export interface ServerTimingSuccess<T> {
+  error: null
+  result: T
+  header: string
+}
+export interface ServerTimingError {
+  result: null
+  error: Error
+  header: string
+}
+export type ServerTimingResult<T> = ServerTimingSuccess<T> | ServerTimingError
+
+export async function serverTiming<T> (
+  name: string,
+  description: string,
+  fn: () => Promise<T>
+): Promise<ServerTimingResult<T>> {
+  const startTime = performance.now()
+
+  try {
+    const result = await fn() // Execute the function
+    const endTime = performance.now()
+
+    const duration = (endTime - startTime).toFixed(1) // Duration in milliseconds
+
+    // Create the Server-Timing header string
+    const header = `${name};dur=${duration};desc="${description}"`
+    return { result, header, error: null }
+  } catch (error: any) {
+    const endTime = performance.now()
+    const duration = (endTime - startTime).toFixed(1)
+
+    // Still return a timing header even on error
+    const header = `${name};dur=${duration};desc="${description}"`
+    return { result: null, error, header } // Pass error with timing info
+  }
+}