lambda_appsync_proc/

lib.rs

#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]
//! This crate provides procedural macros for implementing AWS AppSync Direct Lambda resolvers.
//!
//! It helps convert GraphQL schemas into type-safe Rust code with full AWS Lambda runtime support.
//! The main functionality is provided through the `appsync_lambda_main` and `appsync_operation` macros.
//!
//! # Complete Example
//!
//! ```ignore
//! use lambda_appsync::{appsync_lambda_main, appsync_operation, AppsyncError, ID};
//!
//! // 1. First define your GraphQL schema (e.g. `schema.graphql`):
//! //
//! // type Query {
//! //   players: [Player!]!
//! //   gameStatus: GameStatus!
//! // }
//! //
//! // type Player {
//! //   id: ID!
//! //   name: String!
//! //   team: Team!
//! // }
//! //
//! // enum Team {
//! //   RUST
//! //   PYTHON
//! //   JS
//! // }
//! //
//! // enum GameStatus {
//! //   STARTED
//! //   STOPPED
//! // }
//!
//! // 2. Initialize the Lambda runtime with AWS SDK clients in main.rs:
//!
//! // Optional hook for custom request validation/auth
//! async fn verify_request(
//!     event: &lambda_appsync::AppsyncEvent<Operation>
//! ) -> Option<lambda_appsync::AppsyncResponse> {
//!     // Return Some(response) to short-circuit normal execution
//!     None
//! }
//!
//! // Generate types and runtime setup from schema
//! appsync_lambda_main!(
//!     "schema.graphql",
//!     // Initialize DynamoDB client if needed
//!     dynamodb() -> aws_sdk_dynamodb::Client,
//!     // Enable validation hook
//!     hook = verify_request,
//!     // Enable batch processing
//!     batch = true
//! );
//!
//! // 3. Implement resolver functions for GraphQL operations:
//!
//! #[appsync_operation(query(players))]
//! async fn get_players() -> Result<Vec<Player>, AppsyncError> {
//!     let client = dynamodb();
//!     todo!()
//! }
//!
//! #[appsync_operation(query(gameStatus))]
//! async fn get_game_status() -> Result<GameStatus, AppsyncError> {
//!     let client = dynamodb();
//!     todo!()
//! }
//!
//! // The macro ensures the function signature matches the GraphQL schema
//! // and wires everything up to handle AWS AppSync requests automatically
//! ```

mod appsync_lambda_main;
mod appsync_operation;
mod common;

use proc_macro::TokenStream;

/// 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
///
/// # Example Usage
///
/// ```ignore
/// use lambda_appsync::appsync_lambda_main;
///
/// // If the function returns Some(AppsyncResponse), the Lambda function will immediatly return it
/// // Else, 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 for example.
/// async fn before_request(
///     event: &lambda_appsync::AppsyncEvent<Operation>
/// ) -> Option<lambda_appsync::AppsyncResponse> {
///     todo!()
/// }
///
/// appsync_lambda_main!(
///     // Path to GraphQL schema file
///     "path/to/schema.gql",
///
///     // Optional AWS SDK clients
///     dynamodb() -> aws_sdk_dynamodb::Client,
///     s3() -> aws_sdk_s3::Client,
///
///     // Options
///     batch = true,  // Enable batch request handling
///     hook = before_request, // Add custom request hook, typically used for authentication
///     field_type_override = MyType.field: CustomType // Override generated field types
/// );
/// ```
#[proc_macro]
pub fn appsync_lambda_main(input: TokenStream) -> TokenStream {
    appsync_lambda_main::appsync_lambda_main_impl(input)
}

/// Marks an async function as an AWS AppSync resolver operation, binding it to a specific Query,
/// Mutation or Subscription operation defined in the GraphQL schema.
///
/// The marked function must match the signature of the GraphQL operation, with parameters and return
/// type matching what is defined in the schema. The function will be wired up to handle requests
/// for that operation through the AWS AppSync Direct Lambda resolver.
///
/// # Important
/// This macro can only be used in a crate where the [appsync_lambda_main!] macro has been used at the
/// root level (typically in `main.rs`). The code generated by this macro depends on types and
/// implementations that are created by [appsync_lambda_main!].
///
/// # Example Usage
///
/// ```ignore
/// use lambda_appsync::{appsync_operation, AppsyncError, ID};
///
/// // Execute when a 'getUser' query is received
/// #[appsync_operation(query(getUser))]
/// async fn get_user(id: ID) -> Result<User, AppsyncError> {
///     // Implement resolver logic
///     Ok(dynamodb_get_user(id).await?)
/// }
///
/// // Handle a 'createUser' mutation
/// #[appsync_operation(mutation(createUser))]
/// async fn create_user(name: String, email: String) -> Result<User, AppsyncError> {
///     Ok(dynamodb_create_user(name, email).await?)
/// }
///
/// // Keep the original function name available separately
/// #[appsync_operation(query(getUser), keep_original_function_name)]
/// async fn fetch_user(id: ID) -> Result<User, AppsyncError> {
///     // Can still call fetch_user() directly
///     Ok(dynamodb_get_user(id).await?)
/// }
/// ```
///
/// The macro will ensure the function signature matches what is defined in the GraphQL schema,
/// and wire it up to be called when AWS AppSync invokes the Lambda resolver for that operation.
#[proc_macro_attribute]
pub fn appsync_operation(args: TokenStream, input: TokenStream) -> TokenStream {
    appsync_operation::appsync_operation_impl(args, input)
}