@schemar thanks for sharing your thoughts! Yeah, I fully agree with the spirit of what you’ve written, though I think a few parts of the spec may have been missed.
Aside
I have a WIP blog post(s) that I’m trying to wrap up clarifying a lot of what’s bellow, since people seem to jump to “oh this is a port of HTTP” (different problem space and design), and the way the EIPs folks asked for the text to be laid out is confusing (ie: as just a list of codes, rather than as a table).
I should also mention that the EIP itself is in the process of getting an overhaul (for clarity and adding a bunch of codes after gather feedback from a number of teams the past month). The aforementioned article is mostly to help clarify things for people looking to use the standard, but also to help collect thoughts for the upgrade.
Code Design
Would it help to specify a whole range as application specific successes or failures? E.g. use
0xB*
and0xC*
for app specific failures and successes, respectively?
We’ve designed the codes is as a 2D grid, so it’s easy to parse out the category and reason, so it’s better for programmatic reasoning and developer experience (only have to memorize what 32 numbers mean, not 256). This is much more structured than HTTP, where you have random stuff in each range
that could potentially lead to incompatibility or at least confusion if there will be official meanings assigned to these codes later on. Or for some apps
0xAA
could be a success while for others it is regarded a failure. […] prevents apps from requiring multiple return values (e.g. official code plus app specific code)
Indeed, and this is what we’re seeking to avoid in the spec! The app-specific range still adheres to the same reasons (the rows in the grid) as the rest of the spec. If used correctly, there should be no ambiguity about what each code means at a high level
For example, making 0xA0
mean “success” is not following the spec. 0xA0
must mean “application-specific failure”, 0xAF
must mean “application-specific metadata”, and so on. This range exists only to say “this failure isn’t generic, and has something to do with the specific application’s special domain”. It’s also a way of mapping internal state-machine enums to codes. Consumers of the codes should be able to understand that this is a failure/success/metadata/etc from the lower nibble alone.
Another way (taking up less codes) could be reserving
0xA6
through0xA9
for custom failures and0xAA
through0xAD
for custom success codes. The caller could still reliably identify what’s a success case and what’s a failure case.
Yeah, this is a good idea I’m not sure that it’ll work with the spec as it stands, since we want those reason codes to work universally (the flip side of a more structured approach). That said, we do need to make the spec flexible, but also parsable, so there’s a balance here
Just a thought
It’s good feedback — thank you!
I hope that some of the above clarified parts of spec that were unclear. I’ll noodle on the wider ranges idea