vybekiit 0.7.3 → 0.7.7

package/dist/global-skills/aws-serverless/references/api-gateway.md

@@ -1,21 +1,21 @@
 # API Gateway Reference
 
-Quick-reference for REST API, HTTP API, WebSocket API — debugging, configuration, and quotas.
+Exact quotas and the handful of gotchas worth pinning down. Assumes you know the basics: choose **REST API** when you need WAF / API keys / usage plans / request validation / built-in caching / edge-optimized / canary / VTL / resource policies, otherwise **HTTP API** (lower latency, native JWT, built-in CORS, auto-deploy); under Lambda **proxy** integration the **Lambda must return CORS headers** (the console "Enable CORS" button doesn't apply); the **#1 cause of 502** is a malformed proxy response (`body` must be a `JSON.stringify`'d string in the `{statusCode, headers, body}` shape); REST API has **no native generic JWT** (use Cognito or a Lambda authorizer), HTTP API has a **native JWT authorizer** for any OIDC IdP.
 
 ## Contents
 
-- [REST vs HTTP API Comparison](#rest-vs-http-api-comparison)
-- [CORS Debugging](#cors-debugging)
-- [Lambda Authorizers](#lambda-authorizers)
-- [Throttling and Quotas](#throttling-and-quotas)
+- [REST vs HTTP API comparison](#rest-vs-http-api-comparison)
+- [Integration timeouts and payloads](#integration-timeouts-and-payloads)
+- [Throttling and quotas](#throttling-and-quotas)
+- [Lambda authorizers](#lambda-authorizers)
 - [WebSocket APIs](#websocket-apis)
-- [502/504 Debugging](#502504-debugging)
+- [CORS gotchas](#cors-gotchas)
 
 ---
 
-## REST vs HTTP API Comparison
+## REST vs HTTP API comparison
 
-### Decision Tree
+Default to **HTTP API** (lower latency, lower cost, simpler); reach for **REST API** only when you need one of its exclusive features:
 
 ```
 Need any of these? → REST API
@@ -34,520 +34,100 @@ Need any of these? → REST API
 None of the above? → HTTP API (lower latency, simpler)
 ```
 
-### Feature Comparison
-
-| Feature | REST API | HTTP API |
-|---|---|---|
-| **Latency** | Higher | Lower |
-| **Endpoint types** | Edge, Regional, Private | Regional only |
-| **AWS WAF** | Yes | No |
-| **API keys / usage plans** | Yes | No |
-| **Per-client throttling** | Yes | No |
-| **Request validation** | Yes | No |
-| **Body transformation (VTL)** | Yes | No |
-| **Parameter mapping** | Yes | Yes |
-| **Caching (built-in)** | Yes | No |
-| **Custom domains** | Yes | Yes |
-| **Lambda authorizers** | Yes (TOKEN + REQUEST) | Yes (REQUEST only) |
-| **JWT authorizers (native)** | No | Yes |
-| **IAM auth** | Yes | Yes |
-| **Cognito (native)** | Yes | Yes (via JWT) |
-| **Resource policies** | Yes | No |
-| **Mutual TLS** | Yes | Yes |
-| **CORS setup** | Manual OPTIONS method | Built-in config |
-| **Automatic deployments** | No | Yes |
-| **Canary deployments** | Yes | No |
-| **Custom gateway responses** | Yes | No |
-| **Execution logs** | Yes | No |
-| **Access logs (CloudWatch)** | Yes | Yes |
-| **Access logs (Firehose)** | Yes | No |
-| **X-Ray tracing** | Yes | No |
-| **Mock integrations** | Yes | No |
-| **Private integrations (NLB)** | Yes | Yes |
-| **Private integrations (ALB)** | Yes | Yes |
-| **Private integrations (Cloud Map)** | No | Yes |
-| **Response streaming** | Yes | No |
-| **Console test invocations** | Yes | No |
-| **Integration timeout** | 50ms–29s (configurable) | 30s hard max |
-| **Payload size** | 10 MB | 10 MB |
-
-> **REST API streaming caveats:** Response streaming via REST API proxy integration does not support built-in caching, response transforms (VTL), or WAF inspection of streamed content. Idle timeouts apply, and a 2 MBps bandwidth cap applies after the first 10 MB (Function URLs apply the cap after 6 MB).
-
 ---
 
-## CORS Debugging
-
-### Proxy vs Non-Proxy
+## Integration timeouts and payloads
 
-| Aspect | Proxy integration | Non-proxy integration |
+| | REST API | HTTP API |
 |---|---|---|
-| Who returns CORS headers? | **Your Lambda function** | **API Gateway** (method response) |
-| OPTIONS method needed? | Yes (or use mock) | Yes (mock integration) |
-| Where to configure? | In your code | In API Gateway console/IaC |
-
-### Debugging Flowchart
-
-```
-"Cross-Origin Request Blocked"?
-│
-├─ YES → Which integration type?
-│  │
-│  ├─ PROXY → Lambda MUST return CORS headers
-│  │  ├─ Access-Control-Allow-Origin
-│  │  ├─ Access-Control-Allow-Methods
-│  │  └─ Access-Control-Allow-Headers
-│  │
-│  └─ NON-PROXY → Configure in API Gateway:
-│     ├─ Create OPTIONS method (mock integration)
-│     ├─ Add 200 response with CORS headers
-│     └─ Add CORS headers to actual method responses
-│
-├─ OPTIONS returning 200?
-│  ├─ NO  → OPTIONS method missing or misconfigured
-│  └─ YES → Check actual method response headers
-│
-└─ 502 on OPTIONS?
-   └─ Binary media types set to */* → fix below
-```
-
-### Common CORS Mistakes
-
-| # | Mistake | Fix |
-|---|---|---|
-| 1 | No CORS headers in Lambda (proxy integration) | Add headers to every Lambda response |
-| 2 | Missing OPTIONS method (REST API, non-proxy) | Create OPTIONS with mock integration |
-| 3 | Binary media types `*/*` breaks OPTIONS | Set `contentHandling: CONVERT_TO_TEXT` on OPTIONS |
-| 4 | `Allow-Origin: *` with `credentials: include` | Specify exact origin, not wildcard |
-| 5 | Not redeploying API after CORS changes | Redeploy the stage |
-| 6 | Missing `Allow-Headers` for custom headers | List all headers the client sends |
-| 7 | Gateway 4XX/5XX responses lack CORS headers | Add CORS headers to gateway responses |
-
-### Lambda CORS Headers — Python
-
-```python
-def handler(event, context):
-    return {
-        "statusCode": 200,
-        "headers": {
-            "Access-Control-Allow-Origin": "https://example.com",
-            "Access-Control-Allow-Methods": "OPTIONS,POST,GET,PUT,DELETE",
-            "Access-Control-Allow-Headers": "Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token",
-        },
-        "body": json.dumps({"message": "success"}),
-    }
-```
-
-### Lambda CORS Headers — TypeScript
-
-```typescript
-export const handler = async (event: any) => ({
-  statusCode: 200,
-  headers: {
-    "Access-Control-Allow-Origin": "https://example.com",
-    "Access-Control-Allow-Methods": "OPTIONS,POST,GET,PUT,DELETE",
-    "Access-Control-Allow-Headers": "Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token",
-  },
-  body: JSON.stringify({ message: "success" }),
-});
-```
-
-### Binary Media Types `*/*` Fix
+| Integration timeout | 50ms–29s (default 29s; **raisable only for Regional/private**) | **30s hard max** (lowerable, not raisable) |
+| Payload size | 10 MB | 10 MB |
+| Endpoint types | Edge, Regional, Private | Regional only |
+| Response streaming | Yes (proxy, STREAM mode) | No |
 
-```bash
-# Fix OPTIONS integration request
-aws apigateway update-integration \
-  --rest-api-id API_ID --resource-id RES_ID \
-  --http-method OPTIONS \
-  --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
-
-# Fix OPTIONS integration response
-aws apigateway update-integration-response \
-  --rest-api-id API_ID --resource-id RES_ID \
-  --http-method OPTIONS --status-code 200 \
-  --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT'
-```
+> **REST API streaming caveats:** no built-in caching, no VTL transforms, no WAF inspection of streamed content; 2 MBps cap after the first 10 MB (Function URLs cap after 6 MB).
 
 ---
 
-## Lambda Authorizers
-
-### TOKEN vs REQUEST Authorizer
-
-| Feature | TOKEN | REQUEST |
-|---|---|---|
-| Identity source | Single header (bearer token) | Headers, query strings, stage vars, `$context` |
-| Cache key | Token header value | All specified identity sources |
-| Token validation regex | Yes | No |
-| Fine-grained policies | Limited | Yes (multiple sources) |
-| Available on | REST API only | REST API + HTTP API |
-| **Recommendation** | Legacy | **Preferred** |
-
-> **Use REQUEST authorizers for new APIs.** TOKEN is legacy.
-
-### Caching Behavior
-
-| Setting | Detail |
-|---|---|
-| Default TTL | 300 seconds |
-| Range | 0 (disabled) – 3600 seconds |
-| Cache key (TOKEN) | Header value from token source |
-| Cache key (REQUEST) | All specified identity sources combined |
-| **Critical** | Cached policy applies to **ALL methods/resources** |
-
-If any specified identity source is missing/null/empty → 401 returned **without** invoking Lambda.
-
-### REQUEST Authorizer — Python
-
-```python
-def lambda_handler(event, context):
-    token = event["headers"].get("Authorization", "")
-    is_authorized = verify_token(token)  # Your auth logic
-
-    return {
-        "principalId": "user",
-        "policyDocument": {
-            "Version": "2012-10-17",
-            "Statement": [{
-                "Action": "execute-api:Invoke",
-                "Effect": "Allow" if is_authorized else "Deny",
-                "Resource": event["methodArn"],
-            }],
-        },
-        "context": {"userId": "user", "scope": "read:items"},
-    }
-```
+## Throttling and quotas
 
-### REQUEST Authorizer — TypeScript
-
-```typescript
-import { APIGatewayAuthorizerResult, APIGatewayRequestAuthorizerEvent } from "aws-lambda";
-
-export const handler = async (
-  event: APIGatewayRequestAuthorizerEvent
-): Promise<APIGatewayAuthorizerResult> => {
-  const token = event.headers?.Authorization ?? "";
-  const isAuthorized = verifyToken(token); // Your auth logic
-
-  return {
-    principalId: "user",
-    policyDocument: {
-      Version: "2012-10-17",
-      Statement: [{
-        Action: "execute-api:Invoke",
-        Effect: isAuthorized ? "Allow" : "Deny",
-        Resource: event.methodArn,
-      }],
-    },
-    context: { userId: "user", scope: "read:items" },
-  };
-};
-```
+Throttling applies most-specific → least-specific: per-client/method (usage plan + API key, REST only) → per-method → account-level → AWS Regional (hard). Token bucket: empty bucket → `429 Too Many Requests`; burst allows temporary spikes.
 
-### HTTP API JWT Authorizer (Native — No Lambda)
-
-No Lambda function needed. Configure directly on the API:
-
-```yaml
-# SAM / CloudFormation
-MyHttpApi:
-  Type: AWS::Serverless::HttpApi
-  Properties:
-    Auth:
-      DefaultAuthorizer: MyJwtAuth
-      Authorizers:
-        MyJwtAuth:
-          AuthorizationScopes:
-            - read:items
-          IdentitySource: $request.header.Authorization
-          JwtConfiguration:
-            issuer: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abc123
-            audience:
-              - my-client-id
-```
-
-Supports any OIDC-compliant IdP (Cognito, Auth0, Okta, etc.).
-
----
+### Account-level
 
-## Throttling and Quotas
+Confirm the current account-level steady-state RPS and burst limits for the Region rather than assuming a default — they vary by Region and are adjustable:
 
-### Throttling Hierarchy (Applied in Order)
-
-```
-Most specific → Least specific:
-
-1. Per-client / per-method  (usage plan + API key)   ← REST only
-2. Per-method               (stage method settings)
-3. Account-level            (all APIs in account/Region)
-4. AWS Regional             (hard limit, not changeable)
+```bash
+aws service-quotas get-service-quota --service-code apigateway --quota-code L-8A5B8E43
 ```
 
-### Token Bucket Algorithm
-
-- Tokens added at steady-state rate (RPS)
-- Bucket holds up to burst capacity
-- Each request = 1 token
-- Empty bucket → `429 Too Many Requests`
-- Burst allows temporary spikes above steady-state
-
-### Account-Level Defaults
-
-| Quota | Default | Adjustable? |
-|---|---|---|
-| Steady-state RPS (per Region) | 10,000 | Yes |
-| Burst capacity | 5,000 | Set by AWS based on RPS |
-| Smaller Regions (Cape Town, Milan, Jakarta…) | 2,500 RPS / 1,250 burst | Yes |
-
-### REST API Quotas
+### REST API
 
 | Resource | Default | Adjustable? |
 |---|---|---|
-| Integration timeout | 50ms–29s (default 29s) | Yes (Regional/private only) |
-| Payload size | 10 MB | No |
-| Header value size | 10,240 bytes | No |
-| Cache TTL | 0–3600s | No |
 | Resources per API | 300 | Yes |
 | Stages per API | 10 | Yes |
 | API keys per account | 10,000 | No |
 | Usage plans per account | 300 | Yes |
 | Custom domains per Region | 120 | Yes |
+| Header value size | 10,240 bytes | No |
+| Cache TTL | 0–3600s | No |
 | Mapping template size | 300 KB | No |
 
-### HTTP API Quotas
+### HTTP API
 
 | Resource | Default | Adjustable? |
 |---|---|---|
-| Integration timeout | 30s max | No |
-| Payload size | 10 MB | No |
 | Routes per API | 300 | Yes |
 | Stages per API | 10 | Yes |
 | Integrations per API | 300 | No |
 | Custom domains per Region | 120 | Yes |
 | VPC links per Region | 10 | Yes |
 
-### Usage Plans (REST API Only)
-
-- Per-client rate limits (RPS) and burst limits via API keys
-- Daily/weekly/monthly quotas per key
-- Method-level throttling within a plan (e.g., `GET /pets` = 100 RPS)
-
-### Client-Side 429 Handling
-
-- Exponential backoff with jitter
-- Respect `Retry-After` header
-- Client-side rate limiting to stay under known limits
+Client-side 429 handling: exponential backoff with jitter, respect `Retry-After`, rate-limit to stay under known limits.
 
 ---
 
-## WebSocket APIs
-
-### Route Architecture
+## Lambda authorizers
 
-```
-Client connects    → $connect    (auth, store connectionId)
-Client sends msg   → route selection → custom route or $default
-Server pushes data → @connections API (POST to connectionId)
-Client disconnects → $disconnect (cleanup connectionId)
-```
-
-### Route Selection
-
-- Expression: `$request.body.action` (routes on JSON `action` field)
-- Non-JSON messages → always `$default`
-
-### Predefined Routes
-
-| Route | When | Required? | Notes |
-|---|---|---|---|
-| `$connect` | Connection initiated | No | Auth here; connection pending until integration completes |
-| `$disconnect` | Connection closed | No | Best-effort; connection already closed |
-| `$default` | No matching route / non-JSON | No | Catch-all fallback |
-
-### Connection Management — Python
-
-```python
-import boto3, json
-
-dynamodb = boto3.resource("dynamodb")
-table = dynamodb.Table("WebSocketConnections")
-
-def connect_handler(event, context):
-    table.put_item(Item={"connectionId": event["requestContext"]["connectionId"]})
-    return {"statusCode": 200, "body": "Connected"}
+| Feature | TOKEN | REQUEST |
+|---|---|---|
+| Identity source | Single header (bearer token) | Headers, query strings, stage vars, `$context` |
+| Cache key | Token header value | All specified identity sources combined |
+| Available on | REST API only | REST API + HTTP API |
+| Recommendation | Legacy | **Preferred for new APIs** |
 
-def send_to_client(endpoint_url, connection_id, data):
-    client = boto3.client("apigatewaymanagementapi", endpoint_url=endpoint_url)
-    client.post_to_connection(
-        ConnectionId=connection_id,
-        Data=json.dumps(data).encode("utf-8"),
-    )
-```
+Caching: default TTL **300s** (range 0–3600). **A cached policy applies to ALL methods/resources.** If any specified identity source is missing/null/empty → **401 without invoking Lambda**.
 
-### Connection Management — TypeScript
+The authorizer must return an IAM policy: `{ principalId, policyDocument: { Version, Statement: [{ Action: "execute-api:Invoke", Effect: "Allow"|"Deny", Resource: methodArn }] }, context: {...} }`. HTTP API JWT authorizers need no Lambda — configure `issuer` + `audience` directly on the API.
 
-```typescript
-import { ApiGatewayManagementApiClient, PostToConnectionCommand } from "@aws-sdk/client-apigatewaymanagementapi";
+---
 
-async function sendToClient(endpoint: string, connectionId: string, data: object) {
-  const client = new ApiGatewayManagementApiClient({ endpoint });
-  await client.send(new PostToConnectionCommand({
-    ConnectionId: connectionId,
-    Data: Buffer.from(JSON.stringify(data)),
-  }));
-}
-```
+## WebSocket APIs
 
-### WebSocket Quotas
+Routes: `$connect` (auth, store connectionId), `$disconnect` (best-effort cleanup), `$default` (catch-all / non-JSON), plus custom routes selected by `$request.body.action`. Server pushes via the `@connections` API (`PostToConnectionCommand` / `post_to_connection`).
 
-| Resource | Limit |
+| Limit | Value |
 |---|---|
 | Idle connection timeout | 10 minutes |
 | Max connection duration | 2 hours |
 | Message payload | 128 KB (hard limit) |
 
-### WebSocket Close Codes
+Close codes: **1001** idle/max-duration, 1003 unsupported binary, 1006 abnormal (no close frame), **1008** throttled, **1009** message too large, 1011 internal error, 1012 service restart.
 
-| Code | Meaning |
-|---|---|
-| 1001 | Idle timeout or max duration exceeded |
-| 1003 | Unsupported binary media type |
-| 1005 | No status code present (reserved, not sent on wire) |
-| 1006 | Abnormal closure — no close frame received |
-| 1008 | Throttled (too many requests) |
-| 1009 | Message exceeds size limit |
-| 1011 | Internal server error |
-| 1012 | Service restart |
+Store `connectionId` in DynamoDB with a **TTL attribute set to now + 7200s** (the 2-hour max duration) so stale connections are auto-cleaned even when `$disconnect` is missed — enable DynamoDB TTL on that attribute.
 
 ---
 
-## 502/504 Debugging
-
-### 502 Bad Gateway — Flowchart
+## CORS gotchas
 
-```
-502 Bad Gateway
-│
-├─ Lambda proxy integration?
-│  └─ YES → Check response format (most common cause):
-│     ├─ statusCode: integer (string is coerced, missing defaults to 200)
-│     ├─ headers: object with string values
-│     ├─ body: string (JSON.stringify, not raw object)
-│     └─ Unhandled exception? → Check CloudWatch Logs
-│
-├─ Lambda authorizer?
-│  ├─ Must return valid IAM policy format
-│  ├─ Check authorizer Lambda logs
-│  └─ Authorizer timeout is separate from integration timeout
-│
-├─ HTTP integration?
-│  ├─ Backend reachable from API Gateway?
-│  ├─ Valid HTTP response from backend?
-│  └─ VPC link healthy? (private integration)
-│
-└─ Other causes:
-   ├─ Payload > 10 MB
-   ├─ Binary media types */* (breaks OPTIONS)
-   └─ Stage variable → wrong Lambda alias
-```
-
-### Correct Lambda Response Format
-
-The **most common cause of 502** is an incorrect response format in Lambda proxy integrations.
-
-**Python — Correct:**
-
-```python
-def handler(event, context):
-    return {
-        "isBase64Encoded": False,           # boolean
-        "statusCode": 200,                  # integer, NOT string
-        "headers": {                        # object with string values
-            "Content-Type": "application/json",
-        },
-        "body": json.dumps({"key": "val"}) # MUST be string
-    }
-```
+The common, non-obvious failures (basic header setup is well understood):
 
-**TypeScript — Correct:**
-
-```typescript
-export const handler = async (event: any) => ({
-  isBase64Encoded: false,
-  statusCode: 200,
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ key: "val" }),  // MUST be string
-});
-```
-
-**Common mistakes -> 502:**
-
-```python
-return {"statusCode": 200, "body": {"key": "val"}}     # body not a string -> 502
-return "just a string"                                   # not a JSON object -> 502
-# Note: string statusCode ("200") and missing statusCode are silently handled (no 502)
-```
-
-### 504 Timeout — Flowchart
-
-```
-504 Endpoint Request Timed Out
-│
-├─ Step 1: Enable CloudWatch logging
-│  ├─ REST: execution logs + access logs
-│  ├─ HTTP: access logs only
-│  └─ Include: $context.integrationLatency, $context.integration.status
-│
-├─ Step 2: Identify timeout source
-│  ├─ REST API: integration timeout configurable 50ms–29s
-│  ├─ HTTP API: 30s max (can be lowered, cannot be raised)
-│  └─ Was integration invoked?
-│     ├─ NO  → Transient network failure; retry
-│     └─ YES → Backend too slow
-│
-├─ Step 3: Reduce integration runtime
-│  ├─ Move non-critical work to async (SQS, Step Functions)
-│  ├─ Increase Lambda memory (faster CPU)
-│  ├─ Provisioned concurrency (eliminate cold starts)
-│  └─ Check downstream dependencies (DB, external APIs)
-│
-└─ Step 4: Increase timeout (REST only)
-   ├─ Request via Service Quotas console
-   ├─ Update integration timeout value AND redeploy
-   └─ Note: may reduce account throttle quota
-```
-
-### CloudWatch Insights Queries
-
-**Find all 5xx errors:**
-
-```
-fields @timestamp, @message, @logStream
-| filter status >= 500 and status < 600
-| sort @timestamp desc
-| display @timestamp, httpMethod, resourcePath, status, requestId
-```
-
-**Find timeout errors:**
-
-```
-fields @timestamp, @message
-| filter @message like "Execution failed due to a timeout error"
-| sort @timestamp desc
-```
-
-**Find slow integrations (>10s):**
-
-```
-fields @timestamp, integrationLatency, status, resourcePath
-| filter integrationLatency > 10000
-| sort integrationLatency desc
-```
-
-### Automated Troubleshooting
-
-**AWSSupport-TroubleshootAPIGatewayHttpErrors** — Systems Manager runbook:
+| Mistake | Fix |
+|---|---|
+| Binary media types `*/*` break OPTIONS (502) | Set `contentHandling: CONVERT_TO_TEXT` on the OPTIONS integration |
+| `Allow-Origin: *` with `credentials: include` | Specify the exact origin, not a wildcard |
+| Not redeploying after CORS changes | Redeploy the stage |
+| Gateway 4XX/5XX responses lack CORS headers | Add CORS headers to gateway responses too |
 
-- Validates API, resource, operation, and stage
-- Analyzes CloudWatch logs automatically
-- Requires: `apigateway:GET`, `logs:GetQueryResults`, `logs:StartQuery`, `ssm:*`
-- Available in Systems Manager console → Automation
+For the full step-by-step procedure of wiring CORS, throttling, and access logging when connecting a Lambda, use the **connecting-lambda-to-api-gateway** skill (see SKILL.md routing). For 502/504 deep debugging, see [troubleshooting.md](troubleshooting.md).