submission error messages

joelkoen commented 1 month ago

Description

It would be useful for the client to show more descriptive error messages so that users can understand why submissions may be failing.

With BeaconDB being blocked in some regions, having a more descriptive error message like "connection timed out" would make clear that this is a connection issue, not an error with BeaconDB.

Another thing that would be helpful is if the server was able to send a plain text message that is then displayed to the user on submission. There are various situations where I have thought that such a feature would be useful:

the server can reject requests from old NeoStumbler versions to so that users update to new versions. they can still submit their old data when they update the app, this just helps ensure that users are collecting more accurate data when certain quality issues are fixed in newer versions. 10% of users are using old NeoStumbler versions, despite the latest version being released for more than a month now.
when performing server maintenance, the server can easily reject all submission requests with a message to let the user know, and to suggest trying again later

Suggested implementation

Ichnaea's API docs don't document how errors are returned from the server for geosubmit requests. I'm suggesting the JSON error response from the server could look something like this, based on the geolocate response docs:

{
    "error": {
        "code": 503,
        "message": "BeaconDB submissions are currently down for server maintenance. Please try again later."
    }
}

Additional information

No response

New request

[X] I have checked that a similar feature hasn't been requested yet

joelkoen commented 4 weeks ago

the server can reject requests from old NeoStumbler versions

rereading this, a better solution may be to also support displaying a message from the server on 200 OK

mjaakko commented 3 weeks ago

Sure, no problem with this. I think we can reuse the response format used by the geolocate API (although if it's also used for successful requests, "error" is not semantically correct).

On the server side, you might want to add Retry-After response header so that NeoStumbler can avoid spamming requests when there's maintenance etc. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After

joelkoen commented 3 weeks ago

although if it's also used for successful requests, "error" is not semantically correct

Maybe we could just drop error + code, and rely on the HTTP status?

// HTTP 200

{"message": "You appear to be using a NeoStumbler version that has been out of date for more than three months. Please update to ensure you receive the latest data quality fixes."}

(also I can support something like ?ignore_outdated_version=true to allow users to opt-out of these messages)

And Retry-After is a good idea, I'll make sure to implement that.

mjaakko / NeoStumbler