Diese Seite auf Deutsch

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:

CodeNameWhat happenedTry again?
309INVALID_ARGUMENTthe connection or the endpoint is wrongno, fix the program
1000HTTP_STATUSthe server answered with a status of 400 or higheronly for 429 and 500 – 599
1001CLIENT_UNAVAILABLEthe player isn't online or has no c0de netno
1002REQUESTS_DISABLEDthe player has switched requests off on their computerno
1003REQUEST_FAILEDno connection: unknown host, refused, network downyes
1004REQUEST_TIMEOUTno complete answer within the timeoutyes
1005RESPONSE_TOO_LARGEthe answer is larger than the server allowsno, 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 ​

c0de
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 FUNCTION

Building and running it ​

  1. Bind the laptop to netretry / fetch.
  2. 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 result tries is 1.
  3. Put a variable item server with nothing.invalid in 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 reached

The 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 ​

  • explain turns 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 compares code with the constants: INVALID_ARGUMENT of c0de and c0de_net/http/HTTP_STATUS and the others of c0de net.
  • worthRetrying decides. 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 again is true. Each round sends the request with problem on the CALL line, so no error crashes the process. A successful request resets problem.code to 0, and worthRetrying says FALSE. After the fourth try, the ELSE ends the loop anyway.
  • The wait doubles: wait starts 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 explain and ends with EXIT 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 ​

  1. 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
c0de
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 FUNCTION

HTTP_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.

  1. 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 ​