feat(event-handler): add appsync batch resolvers

[mploski]

Issue Number: #1303

Summary

Support Appsync batching mechanism for Lambda Resolvers

Changes

• Modify Appsync BaseRouter to accept List of AppSyncResolverEventT events alongside singular event
• Store List of AppSyncResolverEventT events in BaseRouter.current_event
• Add Functional test covering batch processing
• Add aws-cdk-aws-appsync-alpha cdk package
• Add end2end tests that
  • deploys AppSync API with lambda resolver and specific schema
  • Validates different resolvers including batching mechanism

User experience

If batch processing is used for specific method, user can access AppSyncResolver events directly in their annotated method and do appropriate processing. Appsync resolver calls method for every event from the coming list of events.

Processing Batch items individually

from typing import List, Optional

from pydantic import BaseModel

from aws_lambda_powertools.event_handler import AppSyncResolver
from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
from aws_lambda_powertools.utilities.typing import LambdaContext

app = AppSyncResolver()


posts = {
    "1": {
        "post_id": "1",
        "title": "First book",
        "author": "Author1",
        "url": "https://amazon.com/",
        "content": "SAMPLE TEXT AUTHOR 1",
        "ups": "100",
        "downs": "10",
    },
    "2": {
        "post_id": "2",
        "title": "Second book",
        "author": "Author2",
        "url": "https://amazon.com",
        "content": "SAMPLE TEXT AUTHOR 2",
        "ups": "100",
        "downs": "10",
    },
    "3": {
        "post_id": "3",
        "title": "Third book",
        "author": "Author3",
        "url": None,
        "content": None,
        "ups": None,
        "downs": None,
    }
}

posts_related = {
    "1": [posts["2"]],
    "2": [posts["3"], posts["1"]],
    "3": [posts["2"], posts["1"]],
}


class Post(BaseModel):
    post_id: str
    author: str
    title: str
    url: str
    content: str
    ups: str
    downs: str

@app.batch_resolver(type_name="Post", field_name="relatedPosts")
def related_posts(event: AppSyncResolverEvent) -> Optional[list]:
    return posts_related[event.source["post_id"]] if event.source else None


def lambda_handler(event, context: LambdaContext) -> dict:
    return app.resolve(event, context)

Processing Batch items at once

from typing import Any, List

from aws_lambda_powertools import Logger
from aws_lambda_powertools.event_handler import AppSyncResolver
from aws_lambda_powertools.utilities.data_classes import AppSyncResolverEvent
from aws_lambda_powertools.utilities.typing import LambdaContext

logger = Logger()
app = AppSyncResolver()


posts_related = {
    "1": {"title": "post1"},
    "2": {"title": "post2"},
    "3": {"title": "post3"},
}


@app.batch_resolver(type_name="Query", field_name="relatedPosts")
def related_posts(event: List[AppSyncResolverEvent]) -> List[Any]:
    results = []

    for record in event:  # (1)!
        post_id = record.arguments.get("post_id")
        try:
            results.append(posts_related[post_id] if post_id else None)
            # Add other logic here
        except Exception:
            logger.error("Error processing record", post_id=post_id)

    return results


def lambda_handler(event, context: LambdaContext) -> dict:
    return app.resolve(event, context)

Under the hood, Router:

1. Recognize we got a list of events so it assumes request coming from appsync batch operations.
2. It registers methods that we want to use to handle batch events. We use for it brand new resolver called batch_resolver.
3. Router finds this method bases on type_name and field_name and calls it for every event in the list. It passes the event itself to it as parameter argument. Optionally it pass user specified parameters if they are present - they are taken from the inside of the event itself. We pass user specified parameters to keep similar UX as with base resolver.
4. Once all events are processed by decorated method, router combines the output from multiple method calls in a form of a list and send it back to the appsync.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 99.25373% with 1 line in your changes missing coverage. Please review.

Project coverage is 96.45%. Comparing base (e14e768) to head (a612e38).
Report is 657 commits behind head on develop.

Files	Patch %	Lines
aws_lambda_powertools/event_handler/appsync.py	98.78%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1998      +/-   ##
===========================================
+ Coverage    96.38%   96.45%   +0.07%     
===========================================
  Files          214      223       +9     
  Lines        10030    10723     +693     
  Branches      1846     1995     +149     
===========================================
+ Hits          9667    10343     +676     
- Misses         259      268       +9     
- Partials       104      112       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[heitorlessa]

Thank you so much for the change, that's much better! Made one comment about favouring composition instead of multiple inheritance (it'll bite us!).

One super helpful change would be to update PR description with a sample UX, so that customers could easily spot what's coming, we could reuse in our docs, and release notes :-)

I'll do a proper review next week

[heitorlessa]

a few changes in GIVEN/WHEN/THEN and usage of response[0].

I'll run the docs locally this afternoon for a proper review!

[heitorlessa]

NOW IT IS COMPLETED! SHIP!

stateDiagram-v2
    direction LR
    LambdaInit: Lambda invocation
    EventHandler: Event Handler
    EventHandlerResolver: Route event based on GraphQL type/field keys
    Client: Client query (listPosts)
    YourLogic: Run your registered resolver function
    EventHandlerResolverBuilder: Verifies response is a list
    AppSyncBatchPostsResolution: query listPosts
    AppSyncBatchPostsItems: get all posts data <em>(id, title, relatedPosts)</em>
    AppSyncBatchRelatedPosts: get related posts <em>(id, title, relatedPosts)</em>
    AppSyncBatchAggregate: aggregate batch resolver event
    AppSyncBatchLimit: reached batch size limit
    LambdaResponse: Lambda response

    Client --> AppSyncBatchResolverMode
    state AppSyncBatchResolverMode {
        [*] --> AppSyncBatchPostsResolution
        AppSyncBatchPostsResolution --> AppSyncBatchPostsItems
        AppSyncBatchPostsItems --> AppSyncBatchRelatedPosts: <strong>N additional queries</strong>
        AppSyncBatchRelatedPosts --> AppSyncBatchRelatedPosts
        AppSyncBatchRelatedPosts --> AppSyncBatchAggregate
        AppSyncBatchRelatedPosts --> AppSyncBatchAggregate
        AppSyncBatchRelatedPosts --> AppSyncBatchAggregate
        AppSyncBatchAggregate --> AppSyncBatchLimit
    }

    AppSyncBatchResolverMode --> LambdaInit: 1x Invoke with N events
    LambdaInit --> EventHandler

    state EventHandler {
        [*] --> EventHandlerResolver: app.resolve(event, context)
        EventHandlerResolver --> YourLogic
        YourLogic --> EventHandlerResolverBuilder
        EventHandlerResolverBuilder --> LambdaResponse
    }

Loading

[leandrodamascena]

APPROVED @heitorlessa! ❤️