Feature request: Add support for AppSync GraphQL resolvers

[leandrodamascena]

Use case

Customers can use AWS Lambda with AWS AppSync to resolve GraphQL fields through two types of integrations:

1. Direct Resolvers – In this approach, no Velocity Template Language (VTL) or JavaScript code is used to transform the payload before invoking the Lambda function. The Lambda receives the full, unmodified GraphQL request context directly from AppSync.

2. Custom Resolvers – This method involves using VTL or JavaScript to modify or transform the request and/or response payloads before the Lambda function is invoked.

While Powertools for AWS can work in some cases with custom resolvers, it is recommended to use Powertools only with direct resolvers. This is because custom resolvers often modify or remove fields in the payload that Powertools depends on to function correctly. Since there is no guaranteed way for customers to ensure these necessary fields remain intact when using custom resolvers, relying on direct resolvers provides a more reliable and consistent integration and avoid Powertools's maintainers trying to identifying issues created by custom integrations.

Payload

Among other fields that I removed just to simplify the example, the payload that AppSync sends to Lambda is something like this:

{
  "arguments": {
    "id": "my identifier"
  },
  "identity": {...},
  "source": null,
  "request": {...},
  "prev": null,
  "info": {
    "selectionSetList": [
      "id",
      "field1",
      "field2"
    ],
    "selectionSetGraphQL": "{\n  id\n  field1\n  field2\n}",
    "parentTypeName": "Mutation",
    "fieldName": "createSomething",
    "variables": {}
  },
  "stash": {}
}

Registering routes

When resolving an event, Powertools needs to examine the fieldName/parentTypeName fields, being fieldName mandatory and parentTypeName optional when creating the routing strategy. In Powertools Python it's something like this:

with fieldName

@app.resolver(field_name="listLocations")
def get_locations(name: str, description: str = "") -> List[Location]: 
    return [{"name": name, "description": description}]

with fieldName and parentTypeName

@app.resolver(type_name="Query", field_name="listLocations")
def get_locations(name: str, description: str = "") -> List[Location]: 
    return [{"name": name, "description": description}]

Transforming arguments into function variables

When working with GraphQL queries like the one below, customers may want to access the post_id variable to query their database or anything related to that. So AppSync sends the Payload with the arguments field and the corresponding name and values, it is recommended to inject those arguments as a function variable.

query

query MyQuery {
  getPost(post_id: "2") {
    id
    title
  }
}

payload

{
"arguments": {
    "post_id": "2"
  },
...
}

resolver

@app.resolver(type_name="Query", field_name="getPost")
def get_locations(post_id: int) -> List[Post]:  # match GraphQL Query arguments
    #do stuff
    return [{"name": name, "description": description}]

Resolver not found

Unlike AppSync events, when the resolver is not found, Powertools should throw a ResolverNotFound exception because the backend of a GraphQL API (Lambda in this case) is expected to perform some operation and return a result to the API (AppSync).

Single and batch resolvers

Customers who want to solve the N+1 problem can use batch resolvers to receive multiple events in the same payload and then resolve them. The keys difference between single resolvers and batch resolvers are:

1/ The return always must be a list and the list of results must match the size and order of the request payload entries so that AWS AppSync can match the results accordingly.
2/ Aggregation - Similar to AppSync events, customers may want to process the entire batch at once or iterate over all items in the batch.
3/ Throw on exception - Customers should have the option to throw an exception or not during batch processing. When customers choose not to throw an exception, Powertools should return None for failed items.

Since Powertools TypeScript already has the whole strategy for registering and resolving routes for AppSync Events, I think the adaptation would be to change the payload fields and deal with batch resolvers, but the other things are more or less the same. I'm more than happy to do a session with you to demonstrate how it works in Powertools Python.

Solution/User Experience

All the expected customer experience was shared in the previous field.

Alternative solutions

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.