When the network fails
Networks fail all the time: Wi-Fi drops, a server restarts, a service is busy. A program that crashes on the first hiccup is annoying. This recipe builds a request that tries again, waiting a little longer each time, and that tells the player in plain words what went wrong when it finally gives up.
Functions: the errors of c0de net, HTTP_GET, and SLEEP of c0de/time
What you need
The mod c0de net in your game, a trigger block with a button, a laptop, two uninitialized variable items, and optionally variable items server and endpoint of type STRING. Without them, the program asks c0de.at for the latest versions of c0de.
The idea
Every function of c0de_net/http raises an error when the request doesn't work out. A CALL with an ERROR variable catches it, and its code says what happened:
| Code | Name | What happened | Try again? |
|---|---|---|---|
| 309 | INVALID_ARGUMENT | the connection or the endpoint is wrong | no, fix the program |
| 1000 | HTTP_STATUS | the server answered with a status of 400 or higher | only for 429 and 500 – 599 |
| 1001 | CLIENT_UNAVAILABLE | the player isn't online or has no c0de net | no |
| 1002 | REQUESTS_DISABLED | the player has switched requests off on their computer | no |
| 1003 | REQUEST_FAILED | no connection: unknown host, refused, network down | yes |
| 1004 | REQUEST_TIMEOUT | no complete answer within the timeout | yes |
| 1005 | RESPONSE_TOO_LARGE | the answer is larger than the server allows | no, ask for less |
The names are constants that hold the codes: INVALID_ARGUMENT is a constant of c0de, and the others come with INCLUDE c0de_net/http, like its functions, as c0de_net/http/HTTP_STATUS and so on. Compare with them instead of the numbers; a program reads better, and a typo is caught when it is checked.
Trying again only helps when the problem may go away by itself. And trying again right away rarely helps: if a server is overloaded, a hundred programs that ask again at once make it worse. So the wait grows with every try – 1 second, 2, 4 – which is called exponential backoff. SLEEP waits a number of game ticks; 20 ticks are a second.
The program
PROGRAM netretry
NOOP
INCLUDE c0de/time
INCLUDE c0de_net/http
NOOP
FUNCTION explain
PARAMETER code INTEGER
PARAMETER status INTEGER 0
RESULT text STRING
BEGIN
ASSIGN text "Unexpected error " ⊕ code ;
IF code = INVALID_ARGUMENT ;
BEGIN
ASSIGN text "The connection settings are wrong" ;
END IF
IF code = c0de_net/http/HTTP_STATUS ;
BEGIN
ASSIGN text "The server refused with status " ⊕ status ;
IF status = 404 ;
BEGIN
ASSIGN text "There is nothing at this address" ;
END IF
IF status = 429 ;
BEGIN
ASSIGN text "Too many requests, try again later" ;
END IF
IF status ≥ 500 ;
BEGIN
ASSIGN text "The server has a problem" ;
END IF
END IF
IF code = c0de_net/http/CLIENT_UNAVAILABLE ;
BEGIN
ASSIGN text "Nobody with c0de net is online" ;
END IF
IF code = c0de_net/http/REQUESTS_DISABLED ;
BEGIN
ASSIGN text "Requests are switched off" ;
END IF
IF code = c0de_net/http/REQUEST_FAILED ;
BEGIN
ASSIGN text "The server can't be reached" ;
END IF
IF code = c0de_net/http/REQUEST_TIMEOUT ;
BEGIN
ASSIGN text "The server is too slow" ;
END IF
IF code = c0de_net/http/RESPONSE_TOO_LARGE ;
BEGIN
ASSIGN text "The answer is too large" ;
END IF
END FUNCTION
NOOP
FUNCTION worthRetrying
PARAMETER code INTEGER
PARAMETER status INTEGER
RESULT result BOOLEAN
BEGIN
ASSIGN result code = c0de_net/http/REQUEST_FAILED OR code = c0de_net/http/REQUEST_TIMEOUT OR ( code = c0de_net/http/HTTP_STATUS AND ( status = 429 OR status ≥ 500 ) ) ;
END FUNCTION
NOOP
FUNCTION fetch
PARAMETER server STRING "c0de.at"
PARAMETER endpoint STRING "/api/version"
RESULT answer STRING
RESULT tries INTEGER
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE problem ERROR
VARIABLE status INTEGER
VARIABLE again BOOLEAN TRUE
VARIABLE wait INTEGER 20
VARIABLE text STRING
ASSIGN api.use_ssl TRUE ;
ASSIGN api.server server ;
ASSIGN api.timeout 10 ;
CALL CLS
WHILE again ;
BEGIN
ASSIGN tries tries + 1 ;
CALL c0de_net/http/HTTP_GET problem
PARAMETER connection api ;
PARAMETER endpoint endpoint ;
RESULT result answer
RESULT status status
CALL worthRetrying
PARAMETER code problem.code ;
PARAMETER status status ;
RESULT result again
IF again AND tries < 4 ;
BEGIN
CALL PRINT
PARAMETER value "Try " ⊕ tries ⊕ " failed, waiting " ⊕ wait ⊕ " ticks" ;
CALL c0de/time/SLEEP
PARAMETER ticks wait ;
ASSIGN wait wait * 2 ;
END
ELSE
BEGIN
ASSIGN again FALSE ;
END IF
END WHILE
IF problem.code ≠ 0 ;
BEGIN
CALL explain
PARAMETER code problem.code ;
PARAMETER status status ;
RESULT text text
CALL PRINT
PARAMETER value text ;
EXIT 1 ;
END IF
CALL PRINT
PARAMETER value answer ;
END FUNCTIONBuilding and running it
- Bind the laptop to
netretry/fetch. - Set the trigger block to
netretry/fetch, put two uninitialized variable items into it, and press the button. The laptop shows the answer,{"c0de":"0.5.0","c0de_net":"0.3.0"}, and the resulttriesis 1. - Put a variable item
serverwithnothing.invalidin it, a name that never exists, and press again. Now the laptop shows:
Try 1 failed, waiting 20 ticks
Try 2 failed, waiting 40 ticks
Try 3 failed, waiting 80 ticks
The server can't be reachedThe exit code is 1, so a comparator can show it. With the server c0de.at and the endpoint /api/nothing, there is no retry: the laptop shows There is nothing at this address after the first try.
How it works
explainturns a code into words. It starts with a message for unknown codes and overwrites it for every code it knows. For HTTP_STATUS, the status says more: 404 is a wrong address, 429 means "too many requests", 500 and above is a problem of the server. It comparescodewith the constants:INVALID_ARGUMENTof c0de andc0de_net/http/HTTP_STATUSand the others of c0de net.worthRetryingdecides. Only REQUEST_FAILED, REQUEST_TIMEOUT and the statuses 429 and 500 and above may go away by themselves. A 404 stays a 404, however often you ask.- The loop runs while
againis true. Each round sends the request withproblemon the CALL line, so no error crashes the process. A successful request resetsproblem.codeto 0, andworthRetryingsaysFALSE. After the fourth try, the ELSE ends the loop anyway. - The wait doubles:
waitstarts at 20 ticks and becomes 40 and 80. SLEEP pauses only this process; the game and other programs go on. - Giving up prints the message of
explainand ends withEXIT 1, so the trigger block reports it without a crash. - Who gets the error. The request is sent from the computer of the player who pressed the button. CLIENT_UNAVAILABLE and REQUESTS_DISABLED are about that player, not about the server – the same program may work for a friend.
Be careful with retries of requests that change something. If a POST times out, the server may have stored the entry anyway, and a retry adds it a second time. GET, HEAD, PUT and DELETE can be repeated safely: asking twice or deleting twice leaves the same result.
Try it yourself
- The to-do list of c0de.at answers errors with a reason in JSON, like
{"error":"no such entry"}. Show the status line and that reason.
Solution
PROGRAM netreason
NOOP
INCLUDE c0de/strings
INCLUDE c0de_net/http
NOOP
FUNCTION why
PARAMETER endpoint STRING "/api/tutorial/todo/99"
RESULT text STRING
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE problem ERROR
VARIABLE unreadable ERROR
VARIABLE answer STRING
VARIABLE reason STRING TAG(json: "error")
ASSIGN api.use_ssl TRUE ;
ASSIGN api.server "c0de.at" ;
ASSIGN api.timeout 10 ;
CALL c0de_net/http/HTTP_GET problem
PARAMETER connection api ;
PARAMETER endpoint endpoint ;
RESULT result answer
ASSIGN text "OK" ;
IF problem.code = c0de_net/http/HTTP_STATUS ;
BEGIN
ASSIGN text problem.message ;
CALL c0de/strings/FROM_JSON unreadable
PARAMETER source answer ;
PARAMETER destination reason ;
IF unreadable.code = 0 ;
BEGIN
ASSIGN text text ⊕ ": " ⊕ reason ;
END IF
END IF
CALL PRINT
PARAMETER value text ;
END FUNCTIONHTTP_GET delivers result also when it raises HTTP_STATUS, so the answer can be read after the error. Not every server answers errors in JSON, so FROM_JSON gets an ERROR variable of its own: if the answer can't be read, the program shows only the status line. For the entry 99, the text is 404 Not Found: no such entry.
- A slow server keeps the player waiting for a long time. Make the program give up sooner.
Solution
Lower api.timeout, for example to 3 seconds. The timeout covers the whole request until the last byte of the answer; with four tries and the waits of 1 + 2 + 4 seconds, the program then gives up after at most 19 seconds instead of 47.
Read more
- Errors of c0de net and How requests are sent
- Errors in the programmer path, and Errors in the guide
- SLEEP
- Exit codes