| name | lambda-api-hosting |
| description | Guia para configurar API .NET 10 com AddAWSLambdaHosting, API Gateway (GATEWAY_STAGE, GATEWAY_PATH_PREFIX) e documentação OpenAPI (Scalar ou Swagger). Use quando criar nova Lambda API .NET, hospedar API no Lambda, configurar AddAWSLambdaHosting, API Gateway, GATEWAY_PATH_PREFIX, GATEWAY_STAGE ou documentação OpenAPI atrás do gateway. |
Lambda API Hosting e Gateway
Guia para configurar APIs .NET 10 hospedadas em AWS Lambda com AddAWSLambdaHosting e tratamento de API Gateway (stage, prefixo de path) e OpenAPI (Scalar ou Swagger UI).
Quando Usar Esta Skill
- Criar nova Lambda com API .NET (endpoints)
- Configurar AddAWSLambdaHosting em projeto ASP.NET Core
- API atrás de API Gateway HTTP API (v2) com prefixo de path e/ou stage nomeado
- GATEWAY_PATH_PREFIX, GATEWAY_STAGE — variáveis e middleware de path
- Documentação OpenAPI (Scalar ou Swagger) quando API está atrás do gateway
Não cobre: Clean Architecture, camadas, UseCases/Controllers (ver core-clean-architecture e core-dotnet).
Fluxo Inicial — Perguntar ao Usuário
Antes de aplicar tratamentos, perguntar:
- Usará documentação OpenAPI? (Scalar e/ou Swagger UI)
- A API será exposta atrás de API Gateway (HTTP API) com prefixo de path e/ou stage nomeado?
Só então configurar middleware de gateway, variáveis de ambiente e OpenAPI server (filter) conforme as respostas.
Variáveis de Ambiente (Gateway)
| Variável | Obrigatória | Uso |
|---|
GATEWAY_PATH_PREFIX | Não | Prefixo que o gateway adiciona antes da Lambda (ex.: /auth). Quando definida, o middleware define PathBase/Path para roteamento. Case-insensitive. |
GATEWAY_STAGE | Não | Nome do stage do HTTP API quando não é $default (ex.: default, dev). O middleware remove esse segmento do path. Se usar $default, não definir. |
API_PUBLIC_BASE_URL | Não | URL base pública (ex.: https://xxx.../dev/auth). Opcional: usado como fallback para o server do OpenAPI quando o doc é gerado sem contexto de request; na prática o filter a partir do request já resolve o "Try it". |
Exemplo de path: Request rawPath = "/default/auth/health" com GATEWAY_STAGE=default e GATEWAY_PATH_PREFIX=/auth → após middleware: PathBase=/auth, Path=/health.
Bootstrap com AddAWSLambdaHosting
No Program.cs, no builder:
using Amazon.Lambda.AspNetCoreServer.Hosting;
builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);
- LambdaEventSource.HttpApi — evento no formato API Gateway HTTP API (v2).
- Rotas da aplicação devem ser definidas sem prefixo nem stage (ex.:
/health, /login); o gateway adiciona externamente.
Pipeline e Middleware de Gateway
Ordem obrigatória: middleware de path antes de UseRouting(), para que o roteamento use o path já reescrito (ver aspnetcore#49454).
app.UseMiddleware<GatewayPathBaseMiddleware>();
app.UseRouting();
Comportamento do middleware:
- GATEWAY_STAGE (se definida): remove o primeiro segmento do path quando coincidir com o stage (case-insensitive). Ex.:
/default/health → Path = /health.
- GATEWAY_PATH_PREFIX (se definida): se o path começar com o prefixo, define
Request.PathBase = prefixo e Request.Path = restante. Ex.: /auth/health → PathBase=/auth, Path=/health. Case-insensitive.
- Ordem de aplicação: primeiro stage, depois prefix. Variáveis não definidas ou vazias: path não é alterado.
Implementar um GatewayPathBaseMiddleware que lê GATEWAY_STAGE e GATEWAY_PATH_PREFIX do ambiente e ajusta context.Request.Path e context.Request.PathBase conforme acima.
OpenAPI (Scalar ou Swagger) com Gateway
Quando o usuário usar OpenAPI (Scalar ou Swagger UI) e API Gateway:
- DocumentFilter (IDocumentFilter) que preenche o Server do OpenAPI a partir do request:
Scheme + Host + segmento de stage (GATEWAY_STAGE) + PathBase. O PathBase no request já reflete o prefixo (ex.: /auth); o stage foi removido pelo middleware, então o filter deve ler GATEWAY_STAGE e prepender ao path do server para URLs como https://.../dev/auth/login.
- Fallback: se
API_PUBLIC_BASE_URL estiver definida, adicionar em AddSwaggerGen com options.AddServer(new OpenApiServer { Url = apiPublicBaseUrl, ... }) para quando o documento for gerado sem contexto de request.
- Registrar o filter:
options.DocumentFilter<OpenApiServerFromRequestFilter>(); (e injetar IHttpContextAccessor no filter). Tanto Swagger UI quanto Scalar consomem o mesmo JSON OpenAPI; o "Try it" usará as URLs corretas.
Handler, Timeout e Evento de Teste
- Handler (AddAWSLambdaHosting sem LambdaEntryPoint): na AWS use apenas o nome do assembly (ex.:
VideoProcessing.Auth.Api, MinhaApi). Não usar formato Assembly::Classe::Método a menos que exista classe de entrada.
- Timeout: mínimo 30 segundos (cold start .NET pode levar 5–15+ s). Padrão de 3 s causa
Sandbox.Timedout.
- Memória: sugerir 512 MB ou mais (melhora cold start).
- Teste no Console da Lambda: com
LambdaEventSource.HttpApi, o evento deve ser API Gateway HTTP API v2. Não usar template "Hello World". Exemplo para GET /health:
{
"version": "2.0",
"routeKey": "GET /health",
"rawPath": "/health",
"rawQueryString": "",
"requestContext": {
"http": { "method": "GET", "path": "/health", "protocol": "HTTP/1.1" },
"routeKey": "GET /health",
"stage": "$default"
},
"headers": {},
"body": null,
"isBase64Encoded": false
}
Checklist IaC (Terraform / CloudFormation / GitHub Actions)
- Runtime: .NET 10 (conforme publish).
- Handler: nome do assembly (ex.:
VideoProcessing.Auth.Api).
- Timeout: ≥ 30 s.
- Memory: 512 MB ou mais.
- Variáveis de ambiente:
GATEWAY_PATH_PREFIX, GATEWAY_STAGE (e opcionalmente API_PUBLIC_BASE_URL) quando a API estiver atrás do gateway.
- Pacote: .zip com saída de
dotnet publish (arquivos na raiz do zip).
Documentação do Projeto
Para detalhes e exemplos de código de referência (middleware, filter OpenAPI, exemplos de path), consulte no repositório:
docs/gateway-path-prefix.md — variáveis, comportamento e exemplos de path.docs/lambda-handler-addawslambdahosting.md — Handler, timeout, evento v2 e resumo IaC.
