gemini - kennedy.gemi.dev

💾 Archived View for zaibatsu.circumlunar.space › ~solderpunk › gemini › status-codes-semi-finalised.… captured on 2023-01-29 at 16:26:26.
-=-=-=-=-=-=-
Status codes semi-finalised
---------------------------

At the end of my last post, in a sleepy and somewhat stressed out
state-of-mind, I started to lean heavily in favour of using a
system where status codes were limited to a single hexadecimal
character, abandoning my carefully-crafted "one point five" digit
system.  To my surprise (but I'm not complaining!) this triggered
almost no commentary from the community.  Having had some time to
think on it, and after exchanging a few emails with Sean, I'm quite
relieved that I had the presence of mind not to just make a snap
decision that night.  I'm now convinced, again, that the two-digit
system with optionally ignorable second digit is the better choice.

The hexadecimal system has the annoyance of needing to specify case
(or case insensitivity); which is admittedly quite a small thing, but
it's an annoying small thing nevertheless and it brings a little bit
of code weight with it which isn't really doing any useful work, so
why not get rid of it?  More seriously, even though the hexadecimal
system intuitively feels lighter/smaller/simpler, it is actually

	more* vulnerable to the kind of unofficial extension that I've been

so worried about all along.  You can spec codes from 0-F, but sooner
or later somebody is going to start serving a G, and then the
floodgates are open to the entire darn alphabet.  Even checking that a
received status is valid, if we want to write a "defensive client"
which rejects anything outside the spec, is a bit of a pain under this
system, as some valid statuses are numeric and others are
alphabetical.

In contrast, the two-digit numeric system, which intuitive feels big
and complexly and overly detailed because there are one whole hundred
unique codes is actually a much more closed system than it appears.
The requirement that the second digit can be ignored by a minimalist
client guarantees that in fact there can never be more than 10
essentially different statuses - this is fewer than the hexadecimal
system allows even *before* it gets extended.  And validating a status
is trivial, because two-digit numbers are easy to recognise, and
there's no ambiguity regarded to case.  It's actually a really great
system.

So, I hereby proclaim that Gemini shall use two-digit codes!

This post's title says status codes are "semi-finalised", because I'm
not ready right here right now to specify the *full* set of two-digit
codes (that'll probably happen this weekend).  But I'm ready to
specify things from the perspective of low-effort implementations
where the second digit is always zero, which I suspect will be
adequate for the vast majority of people right now.  As discussed in
a lot more detail in my last post, the broad categories are:

10	Input required - status code is followed by prompt
20	Success - status code is followed by MIME type
30	Redirect - status code is followed by URL
40	Temporary failure - status code is followed by message
50	Permanent failure - status code is followed by message
60	Certificate required - status code is followed by message

I fully expect basic clients not to implement client certificates,
and to use the same function to handle temporary or permanent errors,
so that gives you just four statuses to handle.

Please update your software!  By the time you read this, I'll have
done mine.