Saltar a contenido

ADR-0001 · Compute: AWS Lambda Node.js 24 ARM64 + API Gateway HTTP API

  • Status: Accepted
  • Date: 2026-04-30
  • Deciders: Cristian Fernández (Zerviz Group)
  • Supersedes: N/A
  • Related: ZEngine/ADR-001-ZEngine-Architecture.md (heredado), docs/discovery/05-gap-analysis.md capability #1.

Context

El ambiente actual usa Lambda nodejs24.x x86_64 con un monolito de 10.242 LoC. La regla base aprobada (checklist §0) dicta greenfield total en ambiente nuevo, soporte multi-tenant N, costo mínimo en dev. El ADR-001 heredado ya valida serverless-first contra Kubernetes/EKS.

Decision

Para todos los servicios services/* del monorepo:

  • Runtime: Node.js 24 LTS (Active LTS hasta oct-2026, Maintenance hasta abr-2028). Soportado nativo por AWS Lambda como nodejs24.x. Node 20 entró en EOL Maintenance abr-2026 ⇒ no aplicable a greenfield. Promoción al siguiente LTS (Node 26) cuando Lambda lo declare GA + ≥6 meses estable.
  • Arquitectura: ARM64 (Graviton2). ~20% más barato que x86_64 a misma performance.
  • Memoria: default 512 MB; servicios IO-bound 256 MB; servicios CPU-heavy 1024 MB. Tuning con AWS Lambda Power Tuning state machine en QA.
  • Timeout: default 10 s (handlers HTTP); 30 s (consumers SQS); 5 min (Saga steps).
  • Empaquetado: container image vía AWS SAM/Terraform Lambda layers para node_modules compartidos (packages/*) — evita el bloating actual (Lambdas con pg/ triplicado).
  • API: API Gateway HTTP API (no REST). Por servicio que expone HTTP, una sola HTTP API con stage default autodeploy. JWT authorizer con Cognito en todas las rutas que no son webhooks externos (ver ADR-0005).
  • Autorización default: JWT (Cognito). Excepción para /webhook/* que usan firma del proveedor (ver ADR-0005).
  • Powertools + X-Ray: activados desde día 1 en todos los Lambdas (ver ADR-0008).
  • Provisioned Concurrency: desactivado en dev, evaluable por servicio en prod si p95 cold-start > 800 ms.

One handler = one Lambda

Antípoda explícita del monolito legacy. Cada ruta del catálogo de servicios mapea a una función dedicada en su services/<name>/handlers/. La domain logic vive en services/<name>/domain/; los side-effects en services/<name>/infrastructure/ (hexagonal).

Consequences

Positive

  • ARM64 reduce costo Lambda ≈ 20%.
  • Single-purpose handlers eliminan blast-radius del monolito (R-05).
  • Container image permite sharing real de packages/* sin layer hell.
  • Powertools + X-Ray dan observability uniforme y multi-tenant (tenant_id en todos los logs/traces).

Negative

  • ARM64 obliga a verificar compatibilidad de algún binario nativo (poco probable con Node puro).
  • Container image cold-start ≈ 200 ms más lento que ZIP en Lambdas pequeñas; mitigable con SnapStart cuando esté en GA para Node, o Provisioned Concurrency.
  • Node 24 introduce APIs nuevas (built-in node:test, URL.canParse, WebSocket cliente nativo). Tests usan Vitest, no node:test, así que sin impacto.

Alternatives considered

  • Fargate / ECS: descartado por ADR-001 heredado (overhead 24/7, no event-driven nativo).
  • Node.js 22 LTS: evaluado, descartado: pasa a Maintenance en oct-2025; Node 24 da +12 meses de Active LTS adicionales para el mismo trabajo de migración.
  • Node.js 26 (release abr-2026): descartado hasta GA en Lambda + ≥6 meses estable.
  • Node.js 20: descartado, EOL Maintenance abr-2026.
  • x86_64: descartado por costo.
  • REST API Gateway: descartado salvo necesidad puntual de validación JSON Schema avanzada.

Tenant-isolation impact

  • Tier lógico: cada Lambda recibe tenant_id desde JWT (custom:tenant_id) o desde event payload normalizado. Powertools logger inyecta automáticamente.
  • Tier físico enterprise: el stack Terraform infra/tenants/<tenant>/ despliega su propia copia de las Lambdas con tenant_id como variable de entorno.

Blast radius

  • Una Lambda caída afecta sólo a su ruta/contexto. Inbound y campañas viven en consumers SQS distintos (ver ADR-0004).
  • VPC config opt-in: sólo Lambdas que tocan RDS necesitan estar en VPC. El resto corre fuera de VPC para evitar ENI cold-start.

Cost note

  • Dev: ARM64 + on-demand + memoria mínima por servicio. Estimado < USD 5/mes en ausencia de tráfico real.
  • QA/Prod: crece con tráfico. 10k msg/día smoke target ≈ USD 30/mes en compute (sin contar APIGW data transfer).

ISO 27001 controls touched

  • A.12.1.1 (procedimientos operacionales documentados): cada servicio tiene runbook en docs/runbooks/<service>.md.
  • A.12.4.1 (event logging): Powertools + CloudWatch + X-Ray.
  • A.14.2.5 (secure system engineering principles): hexagonal + tests de contrato.

Sources

  • docs/discovery/00-phase1-prerequisites.md §1 R-04 + Anexo A-03/A-04.
  • AWS docs: Lambda runtimes, ARM64 pricing.
  • Playbook §2.