Create GraphQL Client

[official-Cromatin]

After both the internal domain and the response DTOs together with thier respective mappers have been put in place and the first test in #3 has been successful, its time to tap into live data.
Doing so requires an GraphQL client.

There are many possible choiches out there like apollo-ios or many others offering some kind of DSL or query builder functionality.
In the scope of a bigger project that might be good to have, but for a MVP its massivly overkill and makes things unneccessary complicated.

Additionally many of the simple clients just do JSON-en/-decoding and HTTP-wrapping under the hood, so nothing complicated.

So what am I going to do now excactly?
I will develop my own simple GraphQL client, utilizing the Client of Vapor.
It will support basic authentication via an APIAuthentication protocol and error handling

[official-Cromatin]

To familiarize myself with the format GraphQL likes to receive data in, I dug into the API of ZFS and tried to replicate it in Hoppscotch.
Fortunately, the network monitor of Firefox proved to be useful in displaying not only the headers and body content but also the request method (which, by the way, must be POST).

Funny how GraphQL still uses complicated REST under the hood.

Anyway, back to explaining how GraphQL works.

Format of the request

In general, the resolver expects the body to be in a JSON format, and the object needs to contain the query field.
If the query sets a parameter in the "definition", these need to be set as well.

The body of one query might look like this:

{
    "query": "...",
    "variables": {
        "...": "...", 
        ...
    }
}

While the request headers might be:

Header	Value	Description
locale	de	Language of the content (like title and description of one dish)
api-key	your-key	Key used for authorization

Format of the response

The response body is in the json format aswell and contains both data and errors (because god forbit, graphql will return no matter what still the 200 http code)

{
    "errors": [
        {...}
    ],
    "data": {
        ...
    }
}

Multiple errors I was able to produce are below:

Invalid token

"errors": [
    {
        "message": "500: Internal Server Error",
        "extensions": {
            "response": {
                "url": "https://wea-food2050-prod-graph-base-4cashw272a-oa.a.run.app/graphql",
                "status": 500,
                "statusText": "Internal Server Error",
                "body": {
                    "errors": [
                        {
                            "message": "Context creation failed: invalid api key",
                            "extensions": {
                                "code": "INTERNAL_SERVER_ERROR"
                            }
                        }
                    ]
                }
            },
            "code": "INTERNAL_SERVER_ERROR"
        }
    }
]

No token passed in headers at all

"errors": [
    {
        "message": "Not authorized to read fields for Outlet",
        "path": [
            "outlet",
            "location"
        ],
        "extensions": {
            "code": "INTERNAL_SERVER_ERROR",
            "serviceName": "base"
        }
    },
    {
        "message": "Not authorized to read fields for Outlet",
        "path": [
            "outlet",
            "calendar"
        ],
        "extensions": {
            "code": "INTERNAL_SERVER_ERROR",
            "serviceName": "base"
        }
    }
]

The main takeaway is that every error object at least has themessage field and optionally the locations, path and extensions fields.
For the moment im just going to handle the message, location and path.

[official-Cromatin]

With the current code flow (as of commit 808f7eb), HTTP errors have the highest priority.

During the development of the ZFVFlavourKitchenRepository, I consistently encountered a 400 (Bad Request) HTTP response code.
After checking the clients code, I realized that I had not yet included a query field from the WeeklyMenuItemsQuery enum.
This important piece of information, actually provided in the response body of the response, was lost by just throwing an generalized httpStatus client error.

There are several ways to address this issue:

1. We can continue relying on the current approach of categorizing client errors into predefined sections, allowing us to alternate their severity by changing the order of checks.
2. We create an interface describing the basic fields that each error (transport, httpStatus, graphql, invalidResponse) will have. These fields will include the HTTP response code, latency, and optionally, the original request and even response struct itself.
   Each error type then will implement this interface and include additional error-specific fields that are crucial for debugging and providing rich insights into the underlying issues.

[official-Cromatin]

I have now settled on the following concept:

Execution of the request

During the processing of the request a GraphQLExecutionContext is build.

1. Before executing the http request

The GraphQLExecutionContext is created after the HTTPRequest is created, but before the request is executed.
Keen eyes might notice that the GraphQLExecutionContext stores a snapshot of the HTTPRequest. In simple terms it is syntactic sugar. Online ressources say that its best practice to signallize that the state of the snapshould should only be read from and not written to.
In my case however I will just create a typealias of the HTTPRequest.

2. While executing the request

The latency of the request (not the whole as processed by the GraphQLClient) is timed and stored as a Duration.
Measuring the elapsed time is done by using the ContinuousClock.
Conveniently when substracting two points in time measured by the ContinuousClock, the result is of the type Duration.

3. After execututing the request

After the request has been executed, the response is stored in the context.
The same snapshot concept that applied for the request, applies for the response aswell.

4. After trying to decode the response body

If, while decoding the response body into the specified type, any errors (DecodingError) are encountered, these are stored aswell.

5. Storing GraphQLError

If the decoded body contains any errors, these are stored aswell.

Deciding what type of error to throw

Using the stored data in the execution context, its evaluated if an exception is thrown and, if so, what type of exception.
The errors are ordered by severity:

1. Transport error (No internet, timeout, ...) -> GraphQLTransportError
2. GraphQL error (invalid query scheme, missing variables, ...) -> GraphQLExecutionError
3. Invalid http code but no GraphQL errors (Too Many Requests, ...) -> GraphQLHTTPError
4. Decoding error (Malformed, missing fields) -> GraphQLResponseFormatError
   If no error occured, the decoded data is returned.