vybekiit 0.7.0 → 0.7.2

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

@@ -1,21 +1,21 @@
 # API Gateway Reference
 
-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.
+Quick-reference for REST API, HTTP API, WebSocket API — debugging, configuration, and quotas.
 
 ## Contents
 
-- [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)
+- [REST vs HTTP API Comparison](#rest-vs-http-api-comparison)
+- [CORS Debugging](#cors-debugging)
+- [Lambda Authorizers](#lambda-authorizers)
+- [Throttling and Quotas](#throttling-and-quotas)
 - [WebSocket APIs](#websocket-apis)
-- [CORS gotchas](#cors-gotchas)
+- [502/504 Debugging](#502504-debugging)
 
 ---
 
-## REST vs HTTP API comparison
+## REST vs HTTP API Comparison
 
-Default to **HTTP API** (lower latency, lower cost, simpler); reach for **REST API** only when you need one of its exclusive features:
+### Decision Tree
 
 ```
 Need any of these? → REST API
@@ -34,100 +34,520 @@ 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).
+
 ---
 
-## Integration timeouts and payloads
+## CORS Debugging
+
+### Proxy vs Non-Proxy
 
-| | REST API | HTTP API |
+| Aspect | Proxy integration | Non-proxy integration |
 |---|---|---|
-| 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 |
+| 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 |
 
-> **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).
+### 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
+```
 
-## Throttling and quotas
+### Common CORS Mistakes
 
-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.
+| # | 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"}),
+    }
+```
 
-### Account-level
+### 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" }),
+});
+```
 
-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:
+### Binary Media Types `*/*` Fix
 
 ```bash
-aws service-quotas get-service-quota --service-code apigateway --quota-code L-8A5B8E43
+# 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'
+```
+
+---
+
+## 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"},
+    }
+```
+
+### 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" },
+  };
+};
 ```
 
-### REST API
+### 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.).
+
+---
+
+## Throttling and Quotas
+
+### 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)
+```
+
+### 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
 
 | 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
+### HTTP API Quotas
 
 | 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 |
 
-Client-side 429 handling: exponential backoff with jitter, respect `Retry-After`, rate-limit to stay under known limits.
+### 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
 
 ---
 
-## Lambda authorizers
+## WebSocket APIs
 
-| 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** |
+### Route Architecture
 
-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**.
+```
+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)
+```
 
-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.
+### Route Selection
 
----
+- Expression: `$request.body.action` (routes on JSON `action` field)
+- Non-JSON messages → always `$default`
 
-## WebSocket APIs
+### 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"}
+
+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"),
+    )
+```
 
-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`).
+### Connection Management — TypeScript
 
-| Limit | Value |
+```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 Quotas
+
+| Resource | Limit |
 |---|---|
 | Idle connection timeout | 10 minutes |
 | Max connection duration | 2 hours |
 | Message payload | 128 KB (hard limit) |
 
-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.
+### WebSocket Close Codes
 
-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.
+| 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 |
 
 ---
 
-## CORS gotchas
+## 502/504 Debugging
 
-The common, non-obvious failures (basic header setup is well understood):
+### 502 Bad Gateway — Flowchart
 
-| 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 |
+```
+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
+    }
+```
+
+**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:
 
-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).
+- Validates API, resource, operation, and stage
+- Analyzes CloudWatch logs automatically
+- Requires: `apigateway:GET`, `logs:GetQueryResults`, `logs:StartQuery`, `ssm:*`
+- Available in Systems Manager console → Automation