NLPRP spec: status code for fetch_from_queue

[ianroberts]

The current NLPRP API specification states that if a client calls fetch_from_queue on a queue_id that is not yet finished processing, then the server should respond with HTTP status code 102 ("Processing"). However status codes below 200 are supposed to be "intermediate" codes and shouldn't be used as the final status of an HTTP exchange - the idea of 102 is that the server can return this intermediate code without closing the connection, as a way to say "I haven't died, I'm still working on it..." and then follow up with a final 200 or higher code when the processing is finished

POST /api/do-expensive-thing

....

102 Processing

102 Processing

200 OK
Content-Type: application/json

{"message":"Processing complete"}

However it's not clear what to suggest instead - it's not a 4xx client error (the request is perfectly valid, it's just that the result isn't yet ready) and it's not a 5xx server error (nothing has actually gone wrong). The most appropriate response would appear to be 202 Accepted:

6.3.3. 202 Accepted The 202 (Accepted) status code indicates that the request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility in HTTP for re-sending a status code from an asynchronous operation.

The 202 response is intentionally noncommittal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled.

Possibly with a response body where the server can indicate some kind of progress counter, if it is able to determine such (e.g. percentage of tasks completed so far).

[RudolfCardinal]

Many thanks for this, and sorry for the delay!

I agree.

Other background docs of relevance:

• https://www.rfc-editor.org/rfc/rfc2518.html#section-10.1 -- RFC2518 (WebDAV extensions), defining code 102 -- "Methods can potentially take a long period of time to process, especially methods that support the Depth header. In such cases the client may time-out the connection while waiting for a response. To prevent this the server may return a 102 (Processing) status code to indicate to the client that the server is still processing the method." -- but also "The server MUST send a final response after the request has been completed", i.e. that 102 means pending but only within a single request/response.
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 -- another version of the 202 definition.
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#information_responses -- overview of all response codes.
• https://evertpot.com/http/102-processing and https://evertpot.com/http/202-accepted -- a blog on these.
• https://softwareengineering.stackexchange.com/questions/316208/http-status-code-for-still-processing, https://stackoverflow.com/questions/51255241/what-http-status-code-should-i-use-for-processing-status-update, and https://stackoverflow.com/questions/9794696/which-http-status-code-means-not-ready-yet-try-again-later -- Stack Overflow discussions.

Changes in https://github.com/ucam-department-of-psychiatry/crate/pull/111:

• NLPRP version from 0.2.0 to 0.3.0 (source + docs).
• CRATE version to 0.20.0
• Alter protocol definition as above.
• CRATE NLPRP server responds to fetch_from_queue as above, providing optional status information.
• CRATE cloud processor (NLPRP client) checks