Error handling for streaming API handlers in the browser, has it ever worked?

[achingbrain]

A few of our APIs are streaming, in that they produce long-lived HTTP responses containing newline-delimited JSON of arbitrary length. When these APIs encounter an error mid-stream, they end the response and write HTTP trailers containing error information.

Thing is, no browsers support HTTP trailers so the browser experience is to end the stream (pull stream, readable stream, etc) with no error message.

It seem there's no plan to add HTTP trailers to the fetch API either, so we need a better way of handling errors. In fact the whole API needs overhauling to be leaner, more consistent and less tied to golang conventions. I did a bunch of work on a RESTful HTTP server for IPFS a while ago, though TBF it could use bringing in line with ipfsx.

Errors though, we could:

1. Deprecate the HTTP API and implement RPC over websockets - this would also allow us to do realtime events

• ✅ Fast (to use)
• ✅ Simple mapping from existing API
• ❌ Big job, incredibly disruptive

2. Chunk streaming responses into multipart messages (e.g. instead of each stream entity being delimited by \n it would be a full-blown message part with appropriate mime-type headers, etc which would let us know if we are about to parse an error or not)

• ✅ Uses existing web conventions
• ❌ Adds overhead for small payloads

3. Return a unique identifier with each response and allow the client to use that id to look up an error for a limited time via an error endpoint

• ❌ Adds complexity

4. Just write the error into the response body and hope the client notices

• ❌ Unsuspecting clients likely to encounter significant surprise

My preference would be for 2, though preferably as part of a wider rethink of the API, a la ipfsx.

[achingbrain]

cc: @ipfs/repos-javascript

[mikeal]

An alternative I would recommend is to simply wrap the existing line separated JSON messages in the metadata we’re looking to replace in the HTTP layer.

So instead of

{ cid: baseEncodedString }

It would be:

{ payload: { cid: baseEncodedString } }

When you need to stream errors or other metadata you can just do it as a top level property:

{ error: { status: 404, message: ‘Block not found’ }}

Chunk streaming responses into multipart messages (e.g. instead of each stream entity being delimited by \n it would be a full-blown message part with appropriate mime-type headers, etc which would let us know if we are about to parse an error or not)

I haven’t found a compelling reason to use multipart messages when the input is not also a multipart message. The format is difficult to parse so implementations tend to be buggy and it’s not any better than just doing your own messages w/ JSON.

Deprecate the HTTP API and implement RPC over websockets - this would also allow us to do realtime events

The one thing I can think of that would make this the most compelling option is if we’re pushing a lot of binary down these streams. With JSON we’re going to suffer base encoding so a new WebSocket based thing would make a lot of sense if we’re serving a lot of block data. Otherwise this seems like a rather large endeavor to shave a few bytes off the response messages.

HTTP Trailers

So, HTTP Trailers are one of several features in HTTP 1.1 that ended up being highly problematic and poorly supported. My general rule is to simply not use them, and I would especially caution against using them for errors.

The naive approach to HTTP, which is what most interfaces take, is that there are two phases: status/headers and body. Once you’ve returned status/headers it’s best to consider HTTP’s role in error messaging complete. Any errors you need to do mid-stream are going to have to be handled in the body, either through messages like I described above or by simply closing the stream prematurely causing a parser error in the client (this is certainly the most common, as anyone who’s dealt with HTTP in the wild has encountered it).

While future versions of HTTP have tried to do a better job at these use cases they still end up being accessed through API’s that assume “HTTP 1.1 semantics” which usually means the naive approach I mentioned above.

[daviddias]

The crux of this issue is not designing a better API, is upgrading the HTTP API itself. We need a migration path for go-ipfs to upgrade its HTTP API in a way that it is non breaking for the users.

One of the attempts was to make it spec first -- https://github.com/ipfs/http-api-spec -- but got superseded by autogen docs.

For more background, read:

• https://github.com/ipfs/specs/issues?q=is%3Aissue+is%3Aopen+label%3Ahttp-api
• https://github.com/ipfs/go-ipfs/issues?q=is%3Aissue+is%3Aopen+label%3Ahttp-api

If only time for one more issue, then my rec is ipfs/specs#208

[achingbrain]

An alternative I would recommend is to simply wrap the existing line separated JSON messages in the metadata we’re looking to replace in the HTTP layer.

To me this looks a lot like what go-IPFS has done with the existing HTTP API. It would be better to use the primitives that HTTP gives us - that is, instead of wrapping things in envelope objects with keys that hint at the content type, just use actual content-types and be done with it.

We need a migration path for go-ipfs to upgrade its HTTP API in a way that it is non breaking for the users.

Agreed, any improvements would have to be done in both codebases. We could do it one command at a time as part of ipfsx as outlined in #2509, the idea it's opt-in initially so people can continue to use the existing API in the interim without breaking anything.

[mikeal]

To me this looks a lot like what go-IPFS has done with the existing HTTP API. It would be better to use the primitives that HTTP gives us - that is, instead of wrapping things in envelope objects with keys that hint at the content type, just use actual content-types and be done with it.

This sounds good, but HTTP doesn’t actually have support for streaming errors. You get one error state in HTTP and that’s the status code, after that you’re on your own. Once you’re parsing the body HTTP’s role in errors is effectively over.

We need a migration path for go-ipfs to upgrade its HTTP API in a way that it is non breaking for the users.

The easiest thing to do would be to put any changed/new API at a new endpoint and leave the old one alone until nobody is using it anymore.