errors types

In a recent pull request, @cel showed that we need different behaviour depending on the different types of errors. https://github.com/ssbc/ssb-ebt/pull/2

I think this is definitely something we need, but I'm wary of using the error messages for that. Because that would make the error messages a public api, not just a user interface. That would mean we couldn't improve the error messages to be something more obvious for the human, because it might break code that looks at the message.

HTTP has status codes, 2xx it worked, 3xx it's somewhere else, 4xx failed, your fault. 5xx failed my fault. I don't think the same codes will work for us, though.

what about, flags for the reason, one of more can be true.

• network: a connection failed somehow, or network unavailable
• cryptography: could not authenticate, decrypt, or a something had the wrong hash.
• api: an api did not exist, or signature used was invalid.
• fs: a file didn't exist, or couldn't be written to.

https://github.com/ssbc/scuttlebot/pull/374 is another PR that involves checking errors. All of these errors would be network type.

But in https://github.com/ssbc/ssb-ebt/pull/2 there is a distinction between a network failure (means the stream is closed) and an api failure (which means ebt is not supported, so carry on)

Okay so my proposal is errors have a small set of keys say, network, crypto, api, fs (suggestions welcome) and then those have properties which are a single camel cased string which identifies the particular error. This would be intended as machine readable, so no changing this once you have made the error.

Bikeshedders, prepare your naming hammers.

@cel @dinosaur @mix @Vendan @andrestaltz any comments on this?

keen!

can you give a specific example of an error? i think i understand the general idea, but not sure exactly what you mean about how an error object would be structured.

also, api seems vague, what about rpc or service? hmm.

in both of those PRs, what we have is some local code wrapping a remote procedure call. the error being handled could be be coming from either the local code, or the remote code, or from the stream connecting them. if an error comes from the rpc stream, it means the rpc connection is broken. in scuttlebot#374, i wanted to check if the error was from the stream. in ssb-ebt#2, i wanted to check for specific error types coming from the remote, or for a stream error. i think both of these could be handled by clarifying the errors produced of the underlying interfaces. e.g. packet-stream or muxrpc could pass a specific error to rpc calls that means "the rpc stream broke", and one that means "the remote rejected this method call". then the consumers of these errors may have to handle them and pass them to their caller, and have to decide whether to pass them through, or wrap them with another error. too much passing through and not enough wrapping is i think why there were so many errors in #374 that all meant "the rpc connection broke" to me.

i like the traditional idea of scalar error types. like with C functions where it is specifically documented which error codes a function might set. (see also man 3 errno). but i can see that making errors into vectors or sets could allow for potentially more expressive error handling.

@HardstyleToaster I agree with you that crypto should be red (because it's like fire) and the network should be blue (because it's like the ocean). But I think the file system should be green (because it's like the forrest). I reckon api errors should be grey/silver (because it represents the city - it's the bit that can just be whatever humans want to make it)

@dinosaur not sure about "rpc" or "service". I figure this error flag would be used for when a function call is called with an incorrect type, I think that covers a missing method too.

I'm just thinking that you'd have a property like error.flags = { network: 'host_unreachable'} something like that.

@cel it's a little tricky to see where you are going with your story - can you express that as a proposal? I think you bring up a good point about wrapping errors, especially since we already do that in quite a few places.

I don't have a clear opinion, and I agree in general this is good to do.

@dinosaur made a good point about "api", "rpc", "service". Everything is an API, so I feel like it's a bit vague. To add a few suggestions, "protocol", "type_mismatch". I kind of like "protocol", because a protocol is a convention that peers should follow but may end up not following for whatever reasons.

Then, I'm not entirely familiar with all the types of errors in the ssb ecosystem but what kind of error would be those that happen when failing to sync data through sneakernet (USB sticks)? "network"? "fs"? something else? Is there a category of replication errors?

hmm, yes the things I had envisioned going into "api" where essentially type errors.

@andrestaltz yeah, I think an error from a USB would be an fs error, but it would have a name that was relavent to usbs.

Seems to be a bikeshed to me. Just do it the way you want to @dominic.

@ev I'm not sure what they way I want it is that is why I started a thread.

@dominic

my proposal is errors have a small set of keys say, network, crypto, api, fs (suggestions welcome) and then those have properties which are a single camel cased string which identifies the particular error. This would be intended as machine readable, so no changing this once you have made the error.

Seems good to me.

@dominic i try to avoid stating proposals unless it is something that i am ready to take action on - otherwise it is just a #somebodyshould.
but here goes:

• packet-stream substream errors that are not originated by the remote api (i.e. that indicate that the rpc stream is broken) should be wrapped into a single error type, like PacketStreamError, or otherwise have some specific flag set.
• muxrpc errors should have specific names like MethodNotFoundError and MethodPermissionError, or otherwise specific flags.
• intermediate code that handles these errors should either pass them through unmodified, or only add properties to them.

@cel Actually, that sounds really good, because the changes are entirely inside muxrpc/packet-stream.

error severity is maybe also useful.