Macro appsync_lambda_main

appsync_lambda_main!() { /* proc-macro */ }

Generates the code required to handle AWS AppSync Direct Lambda resolver events based on a GraphQL schema.

This macro takes a path to a GraphQL schema file and generates the complete foundation for implementing an AWS AppSync Direct Lambda resolver:

• Rust types for all GraphQL types (enums, inputs, objects)
• Query/Mutation/Subscription operation enums
• AWS Lambda runtime setup with logging to handle the AWS AppSync event
• Optional AWS SDK client initialization

Schema Path Argument

The first argument to this macro must be a string literal containing the path to your GraphQL schema file. The schema path can be:

• An absolute filesystem path (e.g. “/home/user/project/schema.graphql”)
• A relative path, that will be relative to your crate’s root directory (e.g. “schema.graphql”, “graphql/schema.gql”)
• When in a workspace context, the relative path will be relative to the workspace root directory

Options

• batch = bool: Enable/disable batch request handling (default: true)
• hook = fn_name: Add a custom hook function for request validation/auth
• exclude_lambda_handler = bool: Skip generation of Lambda handler code
• only_lambda_handler = bool: Only generate Lambda handler code
• exclude_appsync_types = bool: Skip generation of GraphQL type definitions
• only_appsync_types = bool: Only generate GraphQL type definitions
• exclude_appsync_operations = bool: Skip generation of operation enums
• only_appsync_operations = bool: Only generate operation enums
• type_override = Type.field: CustomType: Override type of a specific field
• type_override = Type.field.arg: CustomType: Override type of a field argument
• field_type_override (Deprecated): Same as type_override

AWS SDK Clients

AWS SDK clients can be initialized by providing function definitions that return a cached SDK client type. Each client is initialized only once and stored in a static OnceLock, making subsequent function calls essentially free:

• Function name: Any valid Rust identifier that will be used to access the client
• Return type: Must be a valid AWS SDK client like aws_sdk_dynamodb::Client

use lambda_appsync::appsync_lambda_main;

// Single client
appsync_lambda_main!(
    "schema.graphql",
    dynamodb() -> aws_sdk_dynamodb::Client,
);

// Multiple clients
appsync_lambda_main!(
    "schema.graphql",
    dynamodb() -> aws_sdk_dynamodb::Client,
    s3() -> aws_sdk_s3::Client,
);

These client functions can then be called from anywhere in the Lambda crate:

use crate::{dynamodb, s3};
async fn do_something() {
    let dynamodb_client = dynamodb();
    let s3_client = s3();
    // Use clients...
}

Examples

Basic usage with authentication hook:

use lambda_appsync::{appsync_lambda_main, AppsyncEvent, AppsyncResponse, AppsyncIdentity};

fn is_authorized(identity: &AppsyncIdentity) -> bool {
    todo!()
}

// If the function returns Some(AppsyncResponse), the Lambda function will immediately return it.
// Otherwise, the normal flow of the AppSync operation processing will continue.
// This is primarily intended for advanced authentication checks that AppSync cannot perform, such as verifying that a user is requesting their own ID.
async fn auth_hook(
    event: &lambda_appsync::AppsyncEvent<Operation>
) -> Option<lambda_appsync::AppsyncResponse> {
    // Verify JWT token, check permissions etc
    if !is_authorized(&event.identity) {
        return Some(AppsyncResponse::unauthorized());
    }
    None
}

appsync_lambda_main!(
    "schema.graphql",
    hook = auth_hook,
    dynamodb() -> aws_sdk_dynamodb::Client
);

Generate only types for lib code generation:

use lambda_appsync::appsync_lambda_main;
appsync_lambda_main!(
    "schema.graphql",
    only_appsync_types = true
);

Override field types, operation return type or argument types:

use lambda_appsync::appsync_lambda_main;
appsync_lambda_main!(
    "schema.graphql",
    // Use String instead of the default lambda_appsync::ID
    // Override Player.id to use String instead of ID
    type_override = Player.id: String,
    // Multiple overrides, here changing another `Player` field type
    type_override = Player.team: String,
    // Return value override
    type_override = Query.gameStatus: String,
    type_override = Mutation.setGameStatus: String,
    // Argument override
    type_override = Query.player.id: String,
    type_override = Mutation.deletePlayer.id: String,
    type_override = Subscription.onDeletePlayer.id: String,
);

Disable batch processing:

lambda_appsync::appsync_lambda_main!(
    "schema.graphql",
    batch = false
);