Skip to content

Instantly share code, notes, and snippets.

@duglin
Last active Aug 29, 2015
Embed
What would you like to do?
Docker Error Reporting via REST API
Problem:
Right now the daemon will return errors as plain text in the HTTP body. For example:
$ docker stop qwe
results in:
HTTP/1.1 404 Not Found
Content-Type: text/plain; charset=utf-8
Date: Fri, 21 Nov 2014 19:24:28 GMT
Content-Length: 23
No such container: qwe
This makes it impossible for any kind of i18n support in the future.
Proposal:
- For backwards compatibility we need keep the HTTP body as is
- However, we can add new HTTP headers to the response that will allow for better error processing on the client
- For example:
X-docker-msg-id: 1002
X-docker-msg-arg1: qwe
could be returned in the error case shown above - where "msg-id" is the number for the message, which
can then be used in a message string lookup, and the "msg-argN" values can be used as string/variable substitutions
into the message string returned from the lookup.
- In subsequent versions of Docker, like v2, where can break compatibility, we can move these headers into the
HTTP body - e.g.:
HTTP/1.1 404 Not Found
Content-Type: text/plain; charset=utf-8
Date: Fri, 21 Nov 2014 19:24:28 GMT
Content-Length: xx
{ "msgID": 1002,
"description": "No such container: qwe",
"arg1": "qwe"
}
The "description" field is still provided in the native language of the daemon in case something
goes wrong with the client-side lookup.
- In order for this to work, we need to make sure all errors that bubble back to the HTTP daemon
contain enough information to construct the above JSON:
type Derror struct {
status uint // http status code - if not set will default to 502
msgID uint // string lookup code
args []string // strings to substitutions into error string
}
- Having this should also help in cases in the src code where we look for certain strings in the
'error' type to determine what type of error we have. This is obviously not going to work
if we support other languages on the server, but its also fragile because we can't modify
the error text w/o possibly break the code. Once we have the 'Derror' type we can switch
to looking for a certain msgID's instead. This applies to both the client and daemon sides.
- Once we have the basic infrastructure defined, we can then look to add i18n support.
- We can look into defining constants for these codes, which will be easier to use in the code
but I think that's a secondary concern to agreeing to the overall concept.
- Note we will eventually need this for non-error messages as well but we can start with the
error cases first. Actually, I'd prefer if the REST API always returned JSON for all ops,
when possible, but we can deal with those later. I think dealing with the error cases with
the current APIs is easier and less intrusive.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment