2.1GraphQL types

GraphQL types refers to the types defined in the GraphQL spec. Briefly, these are:

• Scalar, Enum, Object, Input Object, Interface, Union, List
• Scalar includes, at minimum: Int, Float, String, Boolean, ID

GraphQL also allows for custom scalars. Argo supports this, though an @ArgoCodec directive is required to tell Argo how to represent it on the wire.

GraphQL response types refers to the serialization types sketched in the GraphQL spec. These do not have rigorous definitions in the GraphQL spec. These include (but are not limited to):

• Map, List, String, Null
• Optionally, Boolean, Int, Float, and Enum Value

2.2Wire types

Wire types are used by Argo to encode GraphQL values as bytes.

Argo uses the following named Wire types:

• STRING: a UTF-8 string
• BOOLEAN: true or false
• VARINT: a variable-length integer
• FLOAT64: an IEEE 754 double-precision binary floating-point (binary64)
• BYTES: a variable-length byte string
• FIXED: a fixed-length byte string
• RECORD: a selection set, made up of potentially-omittable named fields and their values
• ARRAY: a variable-length list of a single type
• BLOCK: describes how to store the underlying type in a block of value data
• NULLABLE: may be null or have a value
• DESC: a self-describing type

3.1Wire schema serialization

A Wire schema or WireType may be serialized in JSON. It must be a JSON object of the form: {"type": "typeName" ...attributes...} where typeName is one of the Wire types as a string, and the attributes are as sketched in WireType above.

Example № 1{
  "type": "RECORD",
  "fields": [
    {
      "name": "errors",
      "of": {
        "type": "NULLABLE",
        "of": { "type": "ARRAY", "of": { "type": "DESC" } }
      },
      "omittable": true
    }
  ]
}

This serialization may be helpful to avoid recomputing Wire schemas on the server. Other serializations may be more efficient but are out of scope here.

4.1Directives

Argo uses the following directives in a GraphQL schema to customize the wire schema:

enum ArgoCodecType {
  String
  Int
  Float
  Boolean
  BYTES
  FIXED
  DESC
}

directive @ArgoCodec(codec: ArgoCodecType!, fixedLength: Int) on SCALAR | ENUM
directive @ArgoDeduplicate(deduplicate: Boolean! = true) on SCALAR | ENUM

These directives may be omitted when custom scalars are not used and default behavior is desired. Otherwise, they must be added to the GraphQL schema.

@ArgoCodec

Specifies the Wire type to use for a scalar. The @ArgoCodec directive is required for custom scalars, and may be used on any scalar or enum. It specifies the Wire type to use for that scalar or enum.

String, Int, Float, and Boolean match the behavior for these built-in GraphQL types (i.e. they are transformed to STRING, VARINT, FLOAT64, and BOOLEAN respectively). BYTES and FIXED, used for binary data, correspond to those Wire types. DESC corresponds to the self-describing Wire type.

The fixedLength argument is required for FIXED scalars, and specifies the length of the fixed-length binary data. It is an error to specify fixedLength for any other Wire type.

@ArgoDeduplicate

Specifies whether to deduplicate a scalar or enum within a Block.

The @ArgoDeduplicate directive is optional, and may be used on any scalar or enum. The default deduplication behavior (used when the directive is absent) is described above in Creating a Wire schema, and is based on the codec used. Note that deduplication is still only allowed on Labeled types.

4.2Algorithms

A wire schema is generated by the following algorithms. Typically, CollectFieldWireTypes() should be called with the root type of the GraphQL Schema’s operation (typically, Query) along with the selection set—usually from a Query, but potentially for that returned by a Mutation or Subscription.

5.1Message

An Argo Message consists of these concatenated parts:

• A variable-length Header
• 0 or more concatenated Blocks containing scalar values, each prefixed by their length
• 1 Core, which contains the Message’s structure, prefixed by its length

5.2Header

The Header is encoded as a variable-length BitSet. After into a fixed bit array, each bit in the BitSet has a defined meaning described below.

Numbered least to most significant bits:

0: InlineEverything
1: SelfDescribing
2: OutOfBandFieldErrors
3: SelfDescribingErrors
4: NullTerminatedStrings
5: NoDeduplication
6: HasUserFlags

When a given flag is set, Argo’s behavior is modified as described below. Each may also be referred to as a Mode of operation, and the corresponding bit must be set if and only if the messages uses the corresponding Mode.

InlineEverything

In this Mode, Blocks are omitted, along with their length prefixes. Core‘s length prefix is also omitted. Instead, scalar values are written inline in Core (i.e. at the current position when they are encountered).

This generally results in smaller messages which do not compress as well. Useful when the Message will not be compressed. For tiny messages (say, dozens of bytes) this usually results in the smallest possible payloads.

SelfDescribing

In this Mode, Core is written exactly as if its type were DESC. This makes the message value self-describing.

This generally makes the payload much larger, and is primarily useful when debugging.

OutOfBandFieldErrors

In this Mode, GraphQL Field errors are guaranteed not to be written inline, and instead appear in the errors array, if any.

This makes it easier to convert JSON payloads to Argo after the fact, but eliminates the benefits of inline errors.

SelfDescribingErrors

In this Mode, errors are not encoded as usual. Instead, each is encoded as a self-describing value (which must adhere to the GraphQL spec). This applies to both Field errors and Request errors.

This makes it easier to convert JSON payloads to Argo after the fact, but gives less type safety and generally results in larger error payloads.

NullTerminatedStrings

In this Mode, all messages of type String are suffixed with a UTF-8 NUL (i.e. a 0x00 byte). This byte is not included in the String’s length, and is not considered part of the String. Other NUL bytes may still appear within each String.

This makes it possible to implement zero-copy in language environments relying on NUL-terminated strings, but generally makes the payload larger.

NoDeduplication

In this Mode, the message is guaranteed to never use backreferences. This may be because the encoder chose to duplicate values, or because duplicates were never encountered. The decoder MAY safely skip calculating backreference IDs, which carries a small cost.

HasUserFlags

In this Mode, the Header BitSet is followed by another variable-length BitSet called UserFlags. The meaning of entries in UserFlags is up to the implementation, and remain outside the scope of this specification.

This is useful to prototype custom implementations and extensions of Argo.

5.3Blocks

Argo Blocks are named contiguous blocks of encoded scalar values of the same type.

Each begins with a Label encoding the length of the block in bytes (not counting the length prefix).

Concatenated to this is every value in the block. The encoding of each value is defined below. Generally, this will not include any metadata, only values.

The name (or key) of each Block is not encoded in the message.

5.4Core

The Core of a Message contains the primary structure of the payload.

The Core is prefixed with a Label encoding the its length in bytes (not counting the length prefix). This is omitted when operating in InlineEverything mode.

The rest of the Core consists of a single value which encodes the payload. This is almost always a RECORD corresponding to GraphQL’s ExecutionResult.

5.5Label

Argo uses a multipurpose binary marker called a Label which combines several use cases into one compact representation. A Label is written using the variable-length zig-zag coding. A Label is essentially a number which should be interpreted differently according to its value and the context in which it is used.

• For variable-length data, such as a STRING or ARRAY, non-negative values represent the length of the data that is to follow
  • The units depend on the data: STRING lengths are in bytes, while ARRAY lengths are in entries
• For BOOLEANs, 0 means false and 1 means true
• For NULLABLE values, -1 means null
• For NULLABLE values which are not null and are not normally prefixed by a Label, 0 means not-null
  • Values which are prefixed by a Label even when non-nullable omit this non-null marker entirely, since we can rely on the Label’s value to tell us it is not null
• For NULLABLE values, -3 means there was a Field Error which terminated its propagation (if any) here
• For fields which may be omitted—such as fields that come from a selection set over a Union, and therefore may not appear at all—the value -2 is used to represent absence, called the Absent Label
• All other negative numbers are used for Backreferences: identification numbers which refer to values which appeared previously in the Message

Types whose values are prefixed with a Label or are themselves a Label are called Labeled. For example, STRING, ARRAY, BOOLEAN, and all NULLABLE types are Labeled.

Types whose values are not prefixed with a Label and are not themselves a Label are called Unlabeled. For example, non-nullable RECORD and non-nullable FLOAT64 are Unlabeled.

5.6Data encoding

Data are encoded in binary as described here.

STRING

STRING values are encoded as UTF-8 and written to their Block. In Core, a Label is written which is the length of the encoded value in bytes. Typically, repeated STRING values may be deduplicated by instead writing a backreference to Core.

In NullTerminatedStrings mode, an additional UTF-8 NUL (0x00) is written to the block following the UTF-8 value (this is not counted in the length written to Core).

BOOLEAN

BOOLEAN values use the value 0 for false and 1 for true, and are written as a Label to Core.

VARINT

VARINT (variable-length integer) values are written to Core and use the variable-length zig-zag coding.

FLOAT64

FLOAT64 values are written to their Block as 8 bytes in little endian order according to IEEE 754’s binary64 variant. Nothing is written to Core.

BYTES

A BYTES is encoded as unaltered contiguous bytes and written to its Block. In Core, a Label is written which is the length of the encoded value in bytes. Typically, repeated BYTES values may be deduplicated by instead writing a backreference to Core.

FIXED

FIXED values are written to their Block as bytes in little endian order. Nothing is written to Core. The number of bytes is not included in the message in any way, since it is in the Wire schema.

RECORD

RECORD values are written as a concatenation of their Fields to Core. Each Field is written recursively in the order it appears in the Wire schema. If a Field is omittable and absent, it is written as the Absent Label. If a Field is omittable and present, but its underlying type is Unlabeled, a non-null Label is written to Core before writing the field’s value. The number of fields and their types are not included in the message in any way, since that is in the Wire schema.

ARRAY

ARRAY values are written as a Label in Core which contains the ARRAY‘s length (in entries), followed by a concatenation of its entries recursively.

BLOCK

BLOCK is not written to the Message directly. Instead, it modifies its underlying type, naming which block it should be written to and whether values should be deduplicated. Block keys match the name of the type in the GraphQL schema it is generated from. For example, ‘String’ for the built-in type, or a custom scalar’s name. Deduplication is configurable with the ArgoDeduplicate directive, with defaults specified under Wire schema.

NULLABLE

NULLABLE values are written differently depending on whether the underlying value is Labeled or Unlabeled. The value null is always written to Core as the Null Label with the value 0. If the underlying value is present and Labeled, non-null values are simply written recursively and unmodified using the underlying value’s encoding. If the underlying value is present and Unlabeled, first the Non-null Label is written to Core, then the underlying value is written recursively.

DESC

DESC values are self-describing, and primarily used to encode errors. This scheme is described in Self-describing encoding.

PATH

PATH values represent a path into a GraphQL response, such as are used inside Error values. Inline field error paths are relative to the location they appear, and all others are relative to the response root. First, GraphQL spec-compliant paths are transformed to a list of integers as described in Path value transformation. Then, this list of integers is encoded exactly as an ARRAY of VARINT values.

5.7Backreferences

Argo Backreferences are numeric references to values which appeared previously in the Message. Backreferences are encoded as Labels with negative values.

Argo reduces data size on the wire by avoiding repeated values. Whenever a potentially-large value is read or written for the first time in a given Block, it is remembered and given the next available backreference ID number (which is always negative). When it is next used, it can be identified by the backreference ID, eliminating the need to encode (and later decode) the entire value again.

Each Block has a separate backreference ID space. This means backreference IDs are not unique across types: a backreference ID -5 refers to a different value for String than it does for a hypothetical MyEnum. Backreference IDs count down, beginning at the largest non-reserved negative label value: this is -4, since the Error label (-3) is the smallest reserved value.

When encoding, the encoder SHOULD deduplicate by returning backreference IDs instead of re-encoding duplicated values. This is typically implemented with a Map data structure.

When decoding, the decoder MUST track backreference IDs for Blocks with deduplication enabled, usually by storing an array of previously-encountered values. However, this MAY be skipped for messages in NoDeduplication mode.

In order to maintain a compact data representation, backreferences (and therefore deduplication) are only supported for Labeled types. Note that even Unlabeled values may be written to Blocks, to impove compressability.

5.8Errors

Errors require special treatment for three reasons:

1. Field errors are inlined with data (except in OutOfBandFieldErrors Mode). This makes it easy to distinguish between null and an error as soon as a value is read, and also makes their representation more compact.
2. The “extensions” portion of each errors object must be self-describing. This is in contrast to all other data: we don’t know the schema/types of “extensions” data, and it may vary between objects.
3. The “path” portion of each error object is not representable directly in GraphQL (or Argo) types. This is because it mixes String and Int primitive values, which GraphQL forbids for data.

type Location {
  line: Int!
  column: Int!
}

type Error {
  message: String!
  location: [Location!]
  path: PATH
  extensions: DESC
}

6.1HTTP considerations

If a client initiating an Argo HTTP request prefers a specific Argo Mode, it MAY include the Argo-Mode header with the case-insensitive names of the preferred modes separated by semicolons.

Example № 2Argo-Mode: SelfDescribingErrors;OutOfBandFieldErrors

A.1JSON

JSON is the standard serialization for GraphQL data. In the context of GraphQL responses, it has many strengths as well as a few weaknesses.

A.2Tradeoffs

In most cases JSON is a great choice for GraphQL. However, it can be difficult to address the weaknesses. Primarily, these are related to performance: reducing the size of payloads, and reading and writing them quickly.

The value of reading and writing data quickly is self-evident. The benefits of reduced payload sizes can be somewhat more subtle:

• Decreased latency across the stack
  • Most importantly, over the network
    • TCP Slow Start, QUIC Slow Start, and other congestion control mechanisms mean larger first response payloads can significantly increase user-observed latency (especially on app open)
    • Dropped and retried packets are more likely with larger responses, especially over unreliable mobile connections
    • Smaller payloads transfer more quickly
  • Time spent serializing, deserializing, and copying around data
  • Time spent cleaning up data, such as garbage collection
• Increased I/O throughput across the stack

A.3Argo

To address the aforementioned weaknesses, Argo makes a different set of tradeoffs than JSON.

A.4Recommendation

Overall, JSON is the best choice for most GraphQL deployments. However, Argo is a good choice for systems where performance is paramount. Please consider the tradeoffs above.

B.1Ideas which did not pan out

• Use bitmasks on each selection set to mark null (or absent) fields. See Design Notes for more.
• Require all Field Errors be represented inline. This would be nice, but it makes it more difficult to convert JSON responses to Argo. Therefore, this is left as an optional feature (see the OutOfBandFieldErrors flag).
• Specify a Wire type definition for ExecutionResult, particularly errors. Unfortunately, error paths mix string and int, which has no corresponding GraphQL type. We could serialize this all as string and convert back later.
• Make the self-describing format able to describe the Wire format. This made things more complex.
• Avro uses an array format where an arbitrary number of “segments” can be added independently without knowing the final array length, which makes streaming encoding easier. During development Argo was focused on stream support and followed suit, but this was dropped due to lack of compelling GraphQL use cases, and because it conflicted with other techniques (namely Blocks).

B.2Ideas which were not pursued

• Use Label before Floats to represent the number 0s to pad it with. Due to JSON/JS, many doubles are actually smallish Ints, which in IEEE 754 means leading with 0-bytes. This might work out on average, especially since 0 takes only 1 byte.
• Specify how to write compact Paths to values to represent errors. A series of tags.
  • If errors inlined, path up to propagation stop is implicit. The path from there down into any initiating non-nullable field would need to be explicit though, need to account for
• Whenever a default value in encountered for a scalar type which is deduplicatable, implicitly store it with a backreference ID and use it later. This may break if the schema evolves.
• Bake in default backreferences for common strings: ‘line’, ‘column’, ‘path’. For certain small messages, this could make a difference. The extra complexity doesn’t seem worth it though.
• Instead of a self-describing format, simply embed JSON. This is not a knock-out win, especially for the resulting API.
• Use a variable-length compact float format, such as vf128, compact float, or even ASN.1’s REAL BER/DER. This would be most helpful for GraphQL APIs which return many Floats with values near zero. Other options might be ALP: Adaptive Lossless floating-Point Compression or the “Pseudodecimal Encoding” from BtrBlocks.
• Encode the entire ExecutionResult‘s type in each Wire schema, including the errors array. In particular, the user would need to provide their intended extensions format and stick to it, and we’d need to fudge the type of path (which mixes numbers and strings in the GraphQL spec). The upshot would be total elimination of the self-describing format and the inconvenience, inefficiency, and complexity that causes.
• Specifying which types actually use backreferences in a given message could be made more granular. For example, the header could be extended with scheme similar to UserFlags, where a flag is set in the main header and an extra BitSet follows the Flags BitSet. This extra BitSet would set one bit in order for each potentially-deduplicatable type encountered in the message, in order. This could work around client-side inefficiency in bimodal deduplication patterns. However, this seems unlikely to be enough of a problem to justify the complexity.
• Default values. Fields could be marked (in the query or the schema, with query taking precedence) with a default value. Ideally, we would reserve a value (similar to Absent, Null, Error) to indicate when the default is used. (Alternatively, we could reserve/pun the first slot in the backreferences when a type ever uses a default.) This would avoid ever sending the full value, instead of sending it once. This would work best for very large strings which first appear very late in the message, or for non-deduplicatable types (like VARINT) with large encodings which appear many many times. These use cases seem to niche to justify the additional complexity.
• @stream and @defer will likely require additional support. #12 covers some of this. In addition, Blocks will need to become extensible. One scheme for this is to number each block in the same way as Backreferences. Then each new message begins with a Block section, but each block is prefixed with its backreference number. Alternatively, we could include all blocks, but I expect that will mostly be a bunch of zeroes. It will also need to support blocks not seen in the original message (though the possibilities will be known from the query).
• Constant values, outside of CONST_STRING for stream/defer. These are natural extensions, but have no use yet in GraphQL.

C.1Copyright notice

Copyright © 2022, Michael Solomon

THESE MATERIALS ARE PROVIDED “AS IS.” The parties expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE PARTIES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

C.2License

This specification is licensed under OWFa 1.0.

D.1Conformance

A conforming implementation of Argo must fulfill all normative requirements. Conformance requirements are described in this document via both descriptive assertions and key words with clearly defined meanings.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative portions of this document are to be interpreted as described in IETF RFC 2119. These key words may appear in lowercase and still retain their meaning unless explicitly declared as non-normative.

A conforming implementation of Argo may provide additional functionality, but must not where explicitly disallowed or would otherwise result in non-conformance.

D.2Versioning

Argo is versioned using SemVer 2.0.0. Each version of Argo explicitly targets one version of the GraphQL spec, which is usually the latest at time of writing.

F.1Version 1.2

F.2Version 1.1

F.3Version 1.0

Initial release.