@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/guides/fastapi.mdx

@@ -0,0 +1,509 @@
+---
+title: FastAPI
+description: Reference documentation for FastAPI
+generator: py#fast-api
+---
+
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+[FastAPI](https://fastapi.tiangolo.com/) is a framework for building APIs in Python.
+
+The FastAPI generator creates a new FastAPI with AWS CDK or Terraform infrastructure setup. The generated backend uses AWS Lambda for serverless deployment, exposed via an AWS API Gateway API. It sets up [AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda/python/latest/) for observability, including logging, AWS X-Ray tracing and Cloudwatch Metrics.
+
+## Usage
+
+### Generate a FastAPI
+
+You can generate a new FastAPI in two ways:
+
+<RunGenerator generator="py#fast-api" />
+
+### Options
+
+<GeneratorParameters generator="py#fast-api" />
+
+<Snippet name="api/api-choice-note" />
+
+:::tip[API Type]
+Select `ServerlessApiGatewayRestApi` (default) as your `computeType` if you intend to build any streaming operations.
+:::
+
+:::tip[Integration Pattern]
+The `integrationPattern` option defaults to `isolated`, which creates one Lambda per FastAPI operation. Select `shared` if you would prefer a single shared Lambda handler for the whole API, with optional per-operation overrides.
+:::
+
+## Generator Output
+
+The generator will create the following project structure in the `<directory>/<api-name>` directory:
+
+<FileTree>
+
+- project.json Project configuration and build targets
+- pyproject.toml Python project configuration and dependencies
+- run.sh Lambda Web Adapter bootstrap script to start the FastAPI app via uvicorn
+- \<module_name>
+  - \_\_init\_\_.py Module initialisation
+  - init.py Sets the up FastAPI app and configures powertools middleware
+  - main.py API implementation
+- scripts
+  - generate_open_api.py Script to generate an OpenAPI schema from the FastAPI app
+
+</FileTree>
+
+### Infrastructure
+
+<Snippet name="shared-constructs" />
+
+<Snippet name="api/shared-constructs" />
+
+#### Architecture
+
+<Snippet name="api/api-architecture" />
+
+## Implementing your FastAPI
+
+The main API implementation is in `main.py`. This is where you define your API routes and their implementations. Here's an example:
+
+```python
+from pydantic import BaseModel
+from .init import app, tracer
+
+class Item(BaseModel):
+  name: str
+
+@app.get("/items/{item_id}")
+@tracer.capture_method
+def get_item(item_id: int) -> Item:
+    return Item(name=...)
+
+@app.post("/items")
+@tracer.capture_method
+def create_item(item: Item):
+    return ...
+```
+
+The generator sets up several features automatically:
+
+1. AWS Lambda Powertools integration for observability
+2. Error handling middleware
+3. Request/response correlation
+4. Metrics collection
+5. AWS Lambda deployment via [Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) with uvicorn
+6. Type-safe streaming (REST API only)
+
+### Observability with AWS Lambda Powertools
+
+#### Logging
+
+The generator configures structured logging using AWS Lambda Powertools. You can access the logger in your route handlers:
+
+```python
+from .init import app, logger
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int):
+    logger.info("Fetching item", extra={"item_id": item_id})
+    return {"item_id": item_id}
+```
+
+The logger automatically includes:
+
+- Correlation IDs for request tracing
+- Request path and method
+- Lambda context information
+- Cold start indicators
+
+#### Tracing
+
+AWS X-Ray tracing is configured automatically. You can add custom subsegments to your traces:
+
+```python
+from .init import app, tracer
+
+@app.get("/items/{item_id}")
+@tracer.capture_method
+def read_item(item_id: int):
+    # Creates a new subsegment
+    with tracer.provider.in_subsegment("fetch-item-details"):
+        # Your logic here
+        return {"item_id": item_id}
+```
+
+#### Metrics
+
+CloudWatch metrics are collected automatically for each request. You can add custom metrics:
+
+```python
+from .init import app, metrics
+from aws_lambda_powertools.metrics import MetricUnit
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int):
+    metrics.add_metric(name="ItemViewed", unit=MetricUnit.Count, value=1)
+    return {"item_id": item_id}
+```
+
+Default metrics include:
+
+- Request counts
+- Success/failure counts
+- Cold start metrics
+- Per-route metrics
+
+### Error Handling
+
+The generator includes comprehensive error handling:
+
+```python
+from fastapi import HTTPException
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int):
+    if item_id < 0:
+        raise HTTPException(status_code=400, detail="Item ID must be positive")
+    return {"item_id": item_id}
+```
+
+Unhandled exceptions are caught by the middleware and:
+
+1. Log the full exception with stack trace
+2. Record a failure metric
+3. Return a safe 500 response to the client
+4. Preserve the correlation ID
+
+:::tip[Response Models]
+It's recommended to specify response models for your API operations for better code generation if using the `connection` generator. <Link path="guides/connection/react-fastapi#errors">See here for more details</Link>.
+:::
+
+<OptionFilter when={{ computeType: 'ServerlessApiGatewayRestApi' }} description="Streaming — REST API only">
+### Streaming
+
+The generated FastAPI supports streaming responses out of the box when using a REST API. The infrastructure is configured to use the [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to run your FastAPI via uvicorn inside Lambda, with `ResponseTransferMode.STREAM` in API Gateway for all REST API operations, which enables streaming to work alongside non-streaming operations.
+
+#### Using `JsonStreamingResponse`
+
+The generated `init.py` exports a `JsonStreamingResponse` class that provides type-safe streaming with proper OpenAPI schema generation. This ensures that the <Link path="guides/connection/react-fastapi">`connection` generator</Link> can produce correctly typed streaming client methods.
+
+```python
+from pydantic import BaseModel
+from .init import app, JsonStreamingResponse
+
+class Chunk(BaseModel):
+    message: str
+
+async def generate_chunks():
+    for i in range(100):
+        yield Chunk(message=f"This is chunk {i}")
+
+@app.post(
+    "/stream",
+    response_class=JsonStreamingResponse,
+    responses={200: JsonStreamingResponse.openapi_response(Chunk, "Stream of chunks")},
+)
+async def my_stream() -> JsonStreamingResponse:
+    return JsonStreamingResponse(generate_chunks())
+```
+
+The `JsonStreamingResponse` class:
+
+1. Serializes Pydantic models to [JSON Lines](https://jsonlines.org/) format (`application/jsonl`)
+2. Provides an `openapi_response` helper that generates the correct OpenAPI schema with `itemSchema`, enabling the <Link path="guides/connection/react-fastapi#consuming-a-stream">`connection` generator</Link> to produce type-safe streaming client methods
+
+#### Consumption
+
+To consume a stream of responses, you can make use of the <Link path="guides/connection/react-fastapi#consuming-a-stream">`connection` generator</Link> which will provide a type-safe method for iterating over your streamed chunks.
+</OptionFilter>
+
+## Deploying your FastAPI
+
+The FastAPI generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your FastAPI.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The CDK construct for deploying your API in the `common/constructs` folder. You can use this in a CDK application:
+
+```ts {6-8}
+import { MyApi } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    // Add the api to your stack
+    const api = new MyApi(this, 'MyApi', {
+      integrations: MyApi.defaultIntegrations(this).build(),
+    });
+  }
+}
+```
+
+This sets up:
+
+1. An AWS Lambda function for each operation in the FastAPI application
+2. API Gateway HTTP/REST API as the function trigger
+3. IAM roles and permissions
+4. CloudWatch log group
+5. X-Ray tracing configuration
+6. CloudWatch metrics namespace
+
+<Snippet name="api/cors-configuration-cdk-note" />
+
+<OptionFilter when={{ auth: 'Cognito' }} description="Cognito identity construct wiring">
+:::note[Cognito Authentication]
+If you selected to use `Cognito` authentication, you will need to supply the `identity` property to the API construct:
+
+```ts {9}
+import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const identity = new UserIdentity(this, 'Identity');
+
+    const api = new MyApi(this, 'MyApi', {
+      integrations: MyApi.defaultIntegrations(this).build(),
+      identity,
+    });
+  }
+}
+```
+
+The `UserIdentity` construct can be generated using the <Link path="/guides/react-website-auth">`ts#react-website-auth` generator</Link>
+:::
+</OptionFilter>
+
+<OptionFilter when={{ auth: 'Custom' }} description="Custom Lambda Authorizer CDK usage">
+:::caution[Custom Lambda Authorizer]
+When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `authorizer.py` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
+:::
+</OptionFilter>
+</Fragment>
+<Fragment slot="terraform">
+The Terraform modules for deploying your API are in the `common/terraform` folder. You can use this in a Terraform configuration.
+
+The API module stages its Lambda deployment zip in a shared S3 asset bucket — see the <Link path="/guides/terraform-project">Terraform infrastructure guide</Link> for details. Instantiate the `core/asset-bucket` module once per deployment and pass its `bucket_name` output into every API / Lambda module via the `asset_bucket_name` input:
+
+```hcl {1-3, 8}
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
+module "my_api" {
+  source = "../../common/terraform/src/app/apis/my-api"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+
+  # Environment variables for the Lambda function
+  env = {
+    ENVIRONMENT = var.environment
+    LOG_LEVEL   = "INFO"
+  }
+
+  # Additional IAM policies if needed
+  additional_iam_policy_statements = [
+    # Add any additional permissions your API needs
+  ]
+
+  tags = local.common_tags
+}
+```
+
+This sets up:
+
+1. An AWS Lambda function that serves all FastAPI routes
+2. API Gateway HTTP/REST API as the function trigger
+3. IAM roles and permissions
+4. CloudWatch log group
+5. X-Ray tracing configuration
+6. CORS configuration
+
+<Snippet name="api/cors-configuration-terraform-note" />
+
+<OptionFilter when={{ auth: 'Cognito' }} description="Cognito module wiring">
+:::note[Cognito Authentication]
+If you selected to use `Cognito` authentication, you will need to supply the Cognito configuration:
+
+```hcl {3, 5-6}
+module "my_api" {
+  source = "../../common/terraform/src/app/apis/my-api"
+
+  asset_bucket_name    = module.asset_bucket.bucket_name
+
+  user_pool_id         = local.user_pool_id
+  user_pool_client_ids = [local.client_id]
+
+  env = {
+    ENVIRONMENT = var.environment
+    LOG_LEVEL   = "INFO"
+  }
+
+  tags = local.common_tags
+}
+```
+
+You can set up Cognito User Pool and Client using the appropriate Terraform resources or modules.
+:::
+</OptionFilter>
+
+The Terraform module provides several outputs you can use:
+
+```hcl
+# Access the API endpoint
+output "api_url" {
+  value = module.my_api.stage_invoke_url
+}
+
+# Access Lambda function details
+output "lambda_function_name" {
+  value = module.my_api.lambda_function_name
+}
+
+# Access IAM role for granting additional permissions
+output "lambda_execution_role_arn" {
+  value = module.my_api.lambda_execution_role_arn
+}
+```
+
+You can customize CORS settings by passing variables to the module:
+
+```hcl
+module "my_api" {
+  source = "../../common/terraform/src/app/apis/my-api"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+
+  # Custom CORS configuration
+  cors_allow_origins = ["https://myapp.com", "https://staging.myapp.com"]
+  cors_allow_methods = ["GET", "POST", "PUT", "DELETE"]
+  cors_allow_headers = [
+    "authorization",
+    "content-type",
+    "x-custom-header"
+  ]
+
+  tags = local.common_tags
+}
+```
+
+<OptionFilter when={{ auth: 'Custom' }} description="Custom Lambda Authorizer usage with Terraform">
+:::caution[Custom Lambda Authorizer]
+When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `authorizer.py` file before your API will accept any traffic.
+:::
+</OptionFilter>
+</Fragment>
+</Infrastructure>
+
+<OptionFilter when={{ computeType: 'ServerlessApiGatewayRestApi' }} description="WAF — REST APIs get a WAF Web ACL by default">
+### WAF
+
+<Snippet name="api/waf-configuration" parentHeading="WAF" />
+</OptionFilter>
+
+### Integrations
+
+<Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
+
+#### Code Generation
+
+<Infrastructure>
+<Fragment slot="cdk">
+Since operations in FastAPI are defined in Python and CDK infrastructure in TypeScript, we instrument code-generation to supply metadata to the CDK construct to provide a type-safe interface for integrations.
+
+A `generate:<ApiName>-metadata` target is added to the common constructs `project.json` to facilitate this code generation, which emits a file such as `packages/common/constructs/src/generated/my-api/metadata.gen.ts`. Since this is generated at build time, it is ignored in version control.
+
+:::note[Build Before Deploy]
+You will need to run a build whenever you change your API to ensure the types consumed by the CDK construct are up to date.
+
+<PackageManagerShortCommand commands={["build"]} />
+:::
+
+:::tip[Hot Reloading]
+If you are actively working on both your CDK infrastructure and FastAPI together, you can use [`nx watch`](https://nx.dev/nx-api/nx/documents/watch) to regenerate these types every time you make API changes:
+
+<NxCommands
+  commands={[
+    'watch --projects=<FastAPIProject> -- \\ ',
+    'run <InfraProject>:"generate:<ApiName>-metadata"',
+  ]}
+/>
+:::
+</Fragment>
+<Fragment slot="terraform">
+:::note[Terraform Limitations]
+We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iacProvider`.
+:::
+</Fragment>
+</Infrastructure>
+
+<OptionFilter when={{ auth: 'IAM' }} description="IAM-authenticated APIs only">
+### Granting Access (IAM Only)
+
+If you selected to use `IAM` authentication, you can use the `grantInvokeAccess` method to grant access to your API:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts
+api.grantInvokeAccess(myIdentityPool.authenticatedRole);
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+# Create an IAM policy to allow invoking the API
+resource "aws_iam_policy" "api_invoke_policy" {
+  name        = "MyApiInvokePolicy"
+  description = "Policy to allow invoking the FastAPI"
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = "execute-api:Invoke"
+        Resource = "${module.my_api.api_execution_arn}/*/*"
+      }
+    ]
+  })
+}
+
+# Attach the policy to an IAM role (e.g., for authenticated users)
+resource "aws_iam_role_policy_attachment" "api_invoke_access" {
+  role       = aws_iam_role.authenticated_user_role.name
+  policy_arn = aws_iam_policy.api_invoke_policy.arn
+}
+
+# Or attach to an existing role by name
+resource "aws_iam_role_policy_attachment" "api_invoke_access_existing" {
+  role       = "MyExistingRole"
+  policy_arn = aws_iam_policy.api_invoke_policy.arn
+}
+```
+
+The key outputs from the API module that you can use for IAM policies are:
+
+- `module.my_api.api_execution_arn` - For granting execute-api:Invoke permissions
+- `module.my_api.api_arn` - The API Gateway ARN
+- `module.my_api.lambda_function_arn` - The Lambda function ARN
+</Fragment>
+</Infrastructure>
+</OptionFilter>
+
+## Local Development
+
+The generator configures a local development server that you can run with:
+
+<NxCommands commands={['serve my-api']} />
+
+This starts a local FastAPI development server with:
+
+- Auto-reload on code changes
+- Interactive API documentation at `/docs` or `/redoc`
+- OpenAPI schema at `/openapi.json`
+
+## Invoking your FastAPI
+
+To invoke your API from a React website, you can use the <Link path="guides/connection/react-fastapi">`connection` generator</Link>.