Return meaningful errors

[lidel]

iiuc, right now, we seem to return error that produces default error from browser engine:

https://github.com/ipfs-shipyard/helia-service-worker-gateway/blob/41d2cffcff5bc3061212fe13aadb5df9c1a3f64c/src/sw.ts#L389

https://github.com/ipfs-shipyard/helia-service-worker-gateway/blob/41d2cffcff5bc3061212fe13aadb5df9c1a3f64c/src/sw.ts#L387

This makes it hard for user to reason what went wrong, and near to impossible to fill a meaningful error report.

Example: failure to fetch block during path walk

If you walk https://inbrowser.dev/ipns/en.wikipedia-on-ipfs.org long enough, you may hit a hiccup:

Proposed improvement

If we encounter an error while generating a Response within a service worker, we should always catch the error and respond with a meaningful HTML error page.

• return text/html
• human-readable
• include error details (short message, full JS error's stack)
• do this for timeouts and redirects as well
• VERY IMPORTANT UX: have "golden path" for fixing hiccups. HTML big green button "Retry" that allows user to reload page and try again

Pseudocode

async function handleRequest(request) {
  try {
    const response = await fetch(request)
    return response
  } catch (error) {
    // If an error occurs, respond with a custom error page including error details
    const errorResponse = new Response(`
      <h1>Oops! Something went wrong inside of Service Worker IPFS Gateway.</h1>
      <p><button onclick="window.location.reload(true);">🔃 Click here to retry</button>.</p>
      <p>Error details:</p>
      <p>${error.message}</p>
      <pre>${error.stack}</pre>
    `, {
      status: 500,
      statusText: 'Internal Service Worker Gateway Error',
      headers: new Headers({
        'Content-Type': 'text/html'
      })
    })
    return errorResponse
  }
}

[SgtPooki]

IIRC, the body is checked in gateway conformance tests for some failure cases, i.e. https://github.com/ipfs/gateway-conformance/blob/9beb71f432a1e83f2dbc10031612991570ef5397/tests/path_gateway_dag_test.go#L371

We will need some sophisticated handling in verified-fetch to determine whether to surface compliance required error messaging vs error stack traces and whatnot in order to render a useful page here.

Do we want to return this error page HTML from @helia/verified-fetch ?

[lidel]

Good catch, the conformance test you linked is too specific,
should be relaxed to only checking for HTTP 510 status code – opened ipfs/gateway-conformance#205, feel free to skip these two for now.

This allows us to separate concerns, and have branded HTML in service worker:

• verified fetch throws or returns text/plain errors (we don't need to implement HTML errors here)
• service worker gateway catches or wraps them in text/html (see example snipped I posted above)
  • we could limit it to requests for the top level document, and keep plaintext errors for subresources to make debugging easier. (test could be something like const isTopLevelDocumentRequest = request.mode === 'navigate' && request.destination === 'document')

[SgtPooki]

I think verified-fetch will need to return application/json errors in Responses (not text/plain) for us to get a useful stacktrace here.

[lidel]

application/json with stacktrace would be nice, but I think just concatenating err in message returned in return badGatewayResponse(resource, 'Error walking path') will be huge improvement. Right now we lose the meaningful error.