Previously mentioned by @mrc0mmand here.
The Varlink spec for Simple HTTP includes a mapping from Varlink errors to HTTP status codes, but doesn't provide a reverse mapping.
For example, if a server responds to a request with 403 Forbidden, what is the proper way to encode that error when responding to the client? Or, if the client sends a message containing a JSON value with an invalid integer (maybe its outside the 2^53 range, and that server doesn't support it: the spec does only say "SHOULD").
To allow for some form of debugging in this case, Varlink should have a specific error message that is used when the error is not at the Varlink protocol layer, but instead at the transport itself.
# message is human-readable, type is machine-readable
# wrapped contains arbitrary machine-readable data
error ProtocolError(message: ?string, type: ?string, info: ?object)
# Client:
{"method": "org.freedesktop.Hello", "parameters": {"num": 1152921504606846976}}\0
# Server:
{"error": "org.varlink.service.ProtocolError","parameters": {"message": "invalid JSON at offset <n>, integer overflow"}}\0This can also be used when an HTTP server responds with a non-JSON message (ex. getting a 403 Forbidden response), so that a Varlink client can present some kind of error message to the user to help debug the issue.
A server can then decide if the error is unrecoverable or not, and either hangup or just skip until the next NUL-terminated message.
There should also be some pre-defined, machine-readable protocol error types:
| type |
meaning |
info |
org.varlink.service.InvalidJSON |
JSON parsing failed |
offset: ?int |
org.varlink.service.HttpError |
Error occurred at the HTTP layer |
status: ?int, body: ?string |
These are just examples, not a real proposal. There might be a good reason to also include proxy information in these errors so that its possible to determine which proxy caused an error (if there are multiple proxies).
Alternatives
There are a lot of SHOULDs in the spec; perhaps some of them can be converted into protocol negotiation.
For example, defining an option for a server to say what integer range they support for JSON values, or if they support strings-as-integers. The other protocol issues wouldn't be handled though.
Previously mentioned by @mrc0mmand here.
The Varlink spec for Simple HTTP includes a mapping from Varlink errors to HTTP status codes, but doesn't provide a reverse mapping.
For example, if a server responds to a request with 403 Forbidden, what is the proper way to encode that error when responding to the client? Or, if the client sends a message containing a JSON value with an invalid integer (maybe its outside the 2^53 range, and that server doesn't support it: the spec does only say "SHOULD").
To allow for some form of debugging in this case, Varlink should have a specific error message that is used when the error is not at the Varlink protocol layer, but instead at the transport itself.
This can also be used when an HTTP server responds with a non-JSON message (ex. getting a
403 Forbiddenresponse), so that a Varlink client can present some kind of error message to the user to help debug the issue.A server can then decide if the error is unrecoverable or not, and either hangup or just skip until the next NUL-terminated message.
There should also be some pre-defined, machine-readable protocol error types:
org.varlink.service.InvalidJSONorg.varlink.service.HttpErrorThese are just examples, not a real proposal. There might be a good reason to also include proxy information in these errors so that its possible to determine which proxy caused an error (if there are multiple proxies).
Alternatives
There are a lot of
SHOULDs in the spec; perhaps some of them can be converted into protocol negotiation.For example, defining an option for a server to say what integer range they support for JSON values, or if they support strings-as-integers. The other protocol issues wouldn't be handled though.