graphql-go-tools

The grpctest package is a testing utility designed to validate grpc_datasource functionality in graphql-go-tools. It provides a complete ecosystem for testing gRPC-to-GraphQL integration, including:

• Mock gRPC Service: A functional implementation of a product service supporting entity lookups (Product, Storage, Warehouse), queries (filtering, pagination), mutations, and complex types (Unions, Interfaces, Nullable fields).
• GraphQL Schema: A comprehensive schema located in testdata/products.graphqls covering advanced GraphQL features.
• Field Mappings: Logic that maps GraphQL operations, fields, arguments, and enums to their corresponding gRPC/Protobuf counterparts.
• Schema Management: Utilities for loading, parsing, and validating schemas.

Use this package to ensure your grpc_datasource implementation correctly handles request/response mapping, field resolution, error handling, and performance characteristics.

During the Planning phase, the engine decides which datasource fetches each field and in which @defer scope. A planner is uniquely identified by a combination of its datasource and its deferID.

Key behaviors include:

• Scoping: To prevent deferred fields from being accidentally claimed by a non-deferred planner, the engine enforces that a field only joins a planner if their deferID matches. A field with deferID == 0 is considered non-deferred.
• Multiple Planners: A single deferID can result in multiple planners if the deferred fields are reachable from different root anchors (e.g., one from the root query and another from an entity node).
• Defer Parents: The ProcessDefer function identifies 'defer parents'—ancestor nodes on the same datasource that are not themselves deferred but must be part of the path to a deferred field. These ancestors are planned as non-deferred paths to anchor the deferred fetch at a real root (like a root query or an entity node).
• Required Fields: Fields needed for entity resolution (like @key or @requires) are injected with @__defer_internal directives. @requires fields use the requesting field's deferID, while @key fields use the parent's deferID to ensure the key is available before the deferred fetch runs.

type DeferInfo struct {
    ID       int
    Label    string
    ParentID int
}

The Defer Parallel Execution implementation replaces the sequential defer execution loop with a tree-based executor. This allows sibling defers to run concurrently while ensuring child defers only execute after their parent has completed, adhering to the GraphQL specification's parent-before-child ordering guarantee.

Key Components:

• DeferTreeNode: A tree structure (mirroring FetchTreeNode) that organizes defers into Single, Sequence, or Parallel nodes.
• Post-processor: A component that converts DeferDescriptors into a DeferTree during the engine's post-processing phase.
• Tree Resolver: A recursive walker that spawns goroutines for Parallel nodes and executes Sequence nodes in order.
• Concurrency Control: Uses golang.org/x/sync/errgroup for execution and mutexes (on the Loader and during the tree-walk) to protect shared Resolvable and jsonArena resources.

The Abstract Selection Rewriter uses a log-based approach to track the relationship between original field references and new field references created during fragment flattening. Instead of using expensive path-matching or scope-chain heuristics to determine if a field has moved, the rewriter records exact 'provenance' at two specific lifecycle points:

1. Copying: When ast.Document.CopySelection or preserveTypeNameSelection creates a new field from an old one, the relationship is recorded.
2. Merging: When Document.MergeFieldsDefer merges two fields (where one survives and the other is removed), the relationship is recorded.

This allows the rewriter to build two critical maps for consumers:

• fieldRefOrigins: Maps a new reference to all the pre-rewrite references it represents.
• changedFieldRefs: Maps an old reference to its final, post-rewrite replacement.

This design ensures that planner-added fields (like those in skipFieldsRefs) and user-requested fields are correctly disambiguated, even when they occupy the same logical path in the GraphQL response.

When using @defer, the client receives a stream of JSON payloads. The first payload contains the primary data and a pending list. Subsequent payloads contain the incremental data and a completed marker.

Payload Structure

1. Initial Response: Contains the primary data and a pending array announcing which fragments are being deferred. Each entry in pending includes an id and the path to the field.
2. Incremental Payload: Contains the incremental data (correlated by id) and a completed array.
3. Flow Control: The hasNext boolean indicates if more payloads are expected. The payload delivering the last outstanding fragment will have hasNext: false.

Example Stream

Initial response:

{
  "data": {"user": {"name": "Alice"}},
  "pending": [{"id": "1", "path": ["user"]}],
  "hasNext": true
}

Incremental payload:

{
  "incremental": [{"data": {"expensiveField": "..."}, "id": "1"}],
  "completed": [{"id": "1"}],
  "hasNext": false
}

// initial response
{"data":{"user":{"name":"Alice"}},"pending":[{"id":"1","path":["user"]}],"hasNext":true}

// incremental payload
{"incremental":[{"data":{"expensiveField":"..."},"id":"1"}],"completed":[{"id":"1"}],"hasNext":false}

When using @defer, errors are routed to different parts of the response envelope based on whether the error is recoverable (the fragment root survives) or non-recoverable (the fragment root becomes null).

Recoverable Errors

Occur when a nullable field within the deferred fragment errors. The fragment still delivers its data, with the errored field set to null.

• Placement: The error is attached to the incremental item.
• Example: incremental: [{ "data": { "hero": { "name": null } }, "errors": [...], "id": "0" }]

Non-recoverable Errors

Occur when a non-nullable field errors, causing the error to propagate to the fragment root and invalidate the entire fragment.

• Placement: The incremental item is omitted entirely. The error is reported in the completed array.
• Example: completed: [{ "id": "1", "errors": [{ "message": "Cannot return null for non-nullable field ..." }] }]

// Recoverable error (incremental item emitted)
{
  "incremental": [
    { "data": { "hero": { "name": null } }, "errors": [{ "message": "bad" }], "id": "0" }
  ],
  "completed": [{ "id": "0" }],
  "hasNext": false
}

// Non-recoverable error (incremental item omitted)
{
  "completed": [
    { "id": "1", "errors": [{ "message": "Cannot return null for non-nullable field ..." }] }
  ],
  "hasNext": true
}

The project implements a streamed response format for GraphQL @defer directives that aligns with the GraphQL incremental-delivery specification, with specific simplifications regarding nesting and ID allocation.

Response Lifecycle

1. Initial Response: Contains the primary data and a pending array. The pending array declares every @defer in the operation (both top-level and nested) immediately. It also includes hasNext: true.
2. Subsequent Responses: Carry incremental data, completed status, and hasNext. No pending array is emitted in subsequent responses.

Envelope Shapes

Pending Entry

Used only in the initial response to announce deferred fields.

• id: string (the unique identifier for the defer).
• path: string[] (the field-alias-or-name chain from the root to the field enclosing the fragment).
• label: string (optional metadata).

Incremental Entry

Used in subsequent responses to deliver data slices.

• data: object (the deferred data).
• id: string (matches the pending ID).
• errors: array (optional; contains recoverable errors).

Completed Entry

Used to signal a defer has finished.

• Success: { "id": "string" }
• Failure: { "id": "string", "errors": [...] } (contains non-recoverable errors).

Key Deviations from Spec

• Early Disclosure: All nested defers are listed in the initial pending array, rather than being announced lazily when their parent completes.
• ID Granularity: One id is allocated per AST @defer directive, not per list-item. If a @defer is inside a list, all items are returned in a single incremental envelope with one ID.

// Initial response example
{
  "data": { "hero": { "id": "1" } },
  "pending": [
    { "id": "0", "path": ["hero"], "label": "DeferTop" }
  ],
  "hasNext": true
}

// Subsequent response example
{
  "incremental": [
    { "data": { "name": "Luke" }, "id": "0" }
  ],
  "completed": [{ "id": "0" }],
  "hasNext": true
}

In the context of GraphQL @__defer_internal directives, parentDeferId represents the physical tree-ancestry of a deferred field.

For a deferred field to be correctly resolved, it must be parented to the nearest enclosing deferred object. This allows the resolver to traverse into the deferred part of the tree.

During the field merging process, the parentDeferId can become 'stale' if an ancestor's defer directive is removed or merged away. The system must ensure that:

1. Missing parents are added: A field without a parentDeferId is assigned the ID of its nearest enclosing deferred ancestor.
2. Valid parents are preserved: If the parentDeferId still references a live, existing defer ID, it is kept to preserve delivery ordering.
3. Stale parents are repaired: If the parentDeferId references an ID that no longer exists in the live operation tree, it is repaired to point to the nearest enclosing deferred ancestor, or removed if no such ancestor exists.