Network.GRPC.Spec.Serialization

Serialize RPC input

Length-Prefixed-Message → Compressed-Flag Message-Length Message

Compressed-Flag → 0 / 1
                    # encoded as 1 byte unsigned integer
Message-Length  → {length of Message}
                    # encoded as 4 byte unsigned integer (big endian)
Message         → *{binary octet}

Parse input

Serialize RPC output

Parse output

Raw (serialized) form of ResourceHeaders

Invalid resource headers

See parseResourceHeaders

Serialize ResourceHeaders (pseudo headers)

Parse ResourceHeaders (pseudo headers)

Request headers

Request-Headers →
  Call-Definition
  *Custom-Metadata

Parse RequestHeaders

Throws an error if any headers fail to parse; if this is not desired, see parseRequestHeaders' instead.

Parse request headers

This can report invalid headers on a per-header basis; see also parseRequestHeaders.

Serialize Timeout

Parse Timeout

Serialize TraceContext

Parse TraceContext

Build response headers

Parse response headers

Generalization of parseResponseHeaders that does not throw errors

See also Network.GRPC.Spec.parseRequestHeaders versus 'Network.GRPC.Spec.parseRequestHeaders' for a similar pair of functions.

Serialize Pushback

Parse Pushback

Parsing a pushback cannot fail; the spec mandates:

If the value for pushback is negative or unparseble, then it will be seen
as the server asking the client not to retry at all.

We therefore only require Monad m, not MonadError m (having the Monad constraint at all keeps the type signature consistent with other parsing functions).

Build trailers (see buildTrailersOnly for the Trailers-Only case)

Parse response trailers

The gRPC spec defines:

Trailers      → ..
Trailers-Only → HTTP-Status Content-Type Trailers

This means that Trailers-Only is a superset of the Trailers; we make use of this here, and error out if we get an unexpected Content-Type override.

Generalization of parseProperTrailers that does not throw errors.

See also Network.GRPC.Spec.parseRequestHeaders versus 'Network.GRPC.Spec.parseRequestHeaders' for a similar pair of functions. See ProperTrailers' for a discussion of why ProperTrailers' is not parameterized (unlike ResponseHeaders' and RequestHeaders').

Build trailers for the Trailers-Only case

Parse TrailersOnly

Generalization of parseTrailersOnly does that not throw errors.

See also Network.GRPC.Spec.parseRequestHeaders versus 'Network.GRPC.Spec.parseRequestHeaders' for a similar pair of functions.

Classify server response

gRPC servers are supposed to respond with HTTP status 200 OK no matter whether the call was successful or not; if not successful, the information about the failure should be reported using grpc-status and related headers (grpc-message, grpc-status-details-bin).

The gRPC spec mandates that if we get a non-200 status from a broken deployment, we synthesize a gRPC exception with an appropriate status and status message. The spec itself does not provide any guidance on what such an appropriate status would look like, but the official gRPC repo does provide a partial mapping between HTTP status codes and gRPC status codes at https://github.com/grpc/grpc/blob/master/doc/http-grpc-status-mapping.md. This is the mapping we implement here.

Parse CustomMetadata

Serialize CustomMetadata

Serialize binary value (base-64 encoding)

Parse binary value

The presence of duplicate headers makes this a bit subtle. Let's consider an example. Suppose we have two duplicate headers

foo-bin: YWJj    -- encoding of "abc"
foo-bin: ZGVm    -- encoding of "def"

The spec says

Custom-Metadata header order is not guaranteed to be preserved except for
values with duplicate header names. Duplicate header names may have their
values joined with "," as the delimiter and be considered semantically
equivalent.

We will do the decoding of both headers prior to joining duplicate headers, and so the value we will reconstruct for foo-bin is "abc,def".

However, suppose we deal with a (non-compliant) peer which is unaware of binary headers and has applied the joining rule without decoding:

foo-bin: YWJj,ZGVm

The spec is a bit vague about this case, saying only:

Implementations must split Binary-Headers on "," before decoding the
Base64-encoded values.

Here we assume that this case must be treated the same way as if the headers had been decoded prior to joining. Therefore, we split the input on commas, decode each result separately, and join the results with commas again.