graphql.h File Reference

Zero-heap GraphQL executor over a query subset (PROTOCORE_ENABLE_GRAPHQL). More...

#include "protocore_config.h"

Go to the source code of this file.

Detailed Description

Zero-heap GraphQL executor over a query subset (PROTOCORE_ENABLE_GRAPHQL).

The governing standard is not IETF. GraphQL is specified by the GraphQL Foundation and published at spec.graphql.org, released by date. Every section cited in this module is the October 2021 release. There is no RFC for GraphQL.

The document source text is parsed into fixed pools (no heap) by the sec 2 grammar, the operation is executed by the sec 6 algorithms, and the result is serialized as the sec 7.1 response map in the sec 7.2.1 JSON form. The client picks the shape: sec 2.4 says an operation "selects the set of information it needs, and will receive exactly that information and nothing more".

Schema-free model. There is no type system (sec 3). A Field carrying a SelectionSet (obj { a b }, sec 2.5) is completed by executing that selection set; a Field with none is a scalar leaf, completed by calling the resolver (ResolveFieldValue, sec 6.4.2). Arguments met along the path (sec 2.6) stay in scope, so a resolver for sensor.value reads id from sensor(id: 2) { value }. The application implements one function: the value of the scalar at this dotted path, given the arguments in scope.

Supported: one operation, either the sec 2.3 query shorthand ({...}) or query [Name] {...}; nested selection sets (sec 2.4); field arguments (sec 2.6) taking Int, Float, String, Boolean and Null values (sec 2.9.1 to sec 2.9.5); comments (sec 2.1.4) and insignificant commas (sec 2.1.5). Out of scope: mutations and subscriptions (sec 2.3), fragments (sec 2.8), variables (sec 2.10), directives (sec 2.12), aliases (sec 2.7), list values (sec 2.9.7), input objects (sec 2.9.8), block strings and \uXXXX escapes (sec 2.9.4), and lists of objects (sec 3.11). Each parses as a request error.

Two deviations from the released spec, both stated rather than hidden: Int is carried as a 64-bit value where sec 3.5.1 defines a signed 32-bit scalar, and a leaf that fails to resolve completes as null with no errors entry, where sec 7.1.2 says a field error should be listed.

A malformed document raises a request error (sec 7.1.2): execution does not begin and the response map carries errors and no data.

Bounds are compile-time (PROTOCORE_GQL_*); parsing and execution allocate nothing.

The module exports one symbol, GraphQL. Everything in graphql.c has internal linkage.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file graphql.h.