dojo.md 0.1.0 → 0.2.1

package/courses/aws-lambda-debugging/scenarios/level-1/api-gateway-integration.yaml

@@ -0,0 +1,71 @@
+meta:
+  id: api-gateway-integration
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda and API Gateway integration — diagnose response format errors, CORS issues, and proxy integration mismatches"
+  tags: [AWS, Lambda, API-Gateway, CORS, proxy-integration, response-format, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function works when invoked directly but returns 502
+  Bad Gateway when called through API Gateway:
+
+  $ curl https://api.example.com/orders
+  {"message": "Internal server error"}
+
+  API Gateway CloudWatch Logs show:
+  Execution failed due to configuration error:
+  Malformed Lambda proxy response
+
+  The Lambda function returns:
+  return { "statusCode": 200, "body": orders }
+
+  But API Gateway Lambda Proxy Integration requires a specific format:
+  {
+    "statusCode": 200,
+    "headers": { "Content-Type": "application/json" },
+    "body": "{\"orders\": [...]}"  // body MUST be a string!
+  }
+
+  The body must be a JSON string, not an object. And headers must
+  be included.
+
+  After fixing the response format, a CORS error appears:
+  Access to XMLHttpRequest at 'https://api.example.com/orders'
+  from origin 'https://myapp.com' has been blocked by CORS policy:
+  No 'Access-Control-Allow-Origin' header is present.
+
+  CORS headers must be returned by the Lambda function (not just
+  configured in API Gateway for proxy integration):
+  {
+    "statusCode": 200,
+    "headers": {
+      "Content-Type": "application/json",
+      "Access-Control-Allow-Origin": "https://myapp.com",
+      "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type,Authorization"
+    },
+    "body": JSON.stringify({ orders: [...] })
+  }
+
+  Task: Explain API Gateway + Lambda debugging. Write: the proxy
+  integration response format requirement, common response format
+  errors and fixes, CORS with Lambda proxy, API Gateway error codes
+  (502 = malformed response, 504 = Lambda timeout, 403 = auth),
+  and how to test API Gateway integrations.
+
+assertions:
+  - type: llm_judge
+    criteria: "Response format is explained — Lambda proxy integration requires: statusCode (integer), headers (object, optional but recommended), body (string — must JSON.stringify objects!), isBase64Encoded (boolean, for binary). Missing statusCode or non-string body = 502 Malformed Lambda proxy response. Common mistake: returning a raw object instead of JSON.stringify for body. Non-proxy integration allows mapping templates but is more complex to configure"
+    weight: 0.35
+    description: "Response format"
+  - type: llm_judge
+    criteria: "CORS and error codes are covered — CORS with proxy integration: Lambda must return Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Headers in response headers. API Gateway CORS configuration only handles the OPTIONS preflight — actual response headers come from Lambda. Error codes: 502 = malformed Lambda response or Lambda error, 504 = Lambda timeout (API GW has 29s hard limit), 403 = missing/invalid API key or authorizer rejection, 429 = throttled. Check API Gateway execution logs (enable in stage settings) for details"
+    weight: 0.35
+    description: "CORS and errors"
+  - type: llm_judge
+    criteria: "Testing approach is practical — test Lambda independently first: aws lambda invoke. Then test via API Gateway: use the API Gateway console's test feature (shows request/response transformation). Use curl -v to see full HTTP response headers. Enable API Gateway execution logging (detailed) for debugging. Check both Lambda CloudWatch Logs and API Gateway CloudWatch Logs. Use AWS SAM CLI (sam local start-api) for local testing of the full API Gateway → Lambda integration. Postman or httpie for systematic API testing"
+    weight: 0.30
+    description: "Testing approach"

package/courses/aws-lambda-debugging/scenarios/level-1/cloudwatch-logs-basics.yaml

@@ -0,0 +1,64 @@
+meta:
+  id: cloudwatch-logs-basics
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda with CloudWatch Logs — read log streams, understand the REPORT line, and use structured logging for effective debugging"
+  tags: [AWS, Lambda, CloudWatch, logs, REPORT, structured-logging, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function returns an error but you don't know why.
+  Time to check the logs:
+
+  $ aws logs filter-log-events \
+    --log-group-name /aws/lambda/process-order \
+    --start-time 1701432000000
+
+  Each invocation produces these log entries:
+
+  START RequestId: abc-123 Version: $LATEST
+  2024-12-01T10:00:00.123Z abc-123 INFO Processing order: ORD-456
+  2024-12-01T10:00:00.456Z abc-123 INFO Fetching customer: CUST-789
+  2024-12-01T10:00:01.789Z abc-123 ERROR Customer not found: CUST-789
+  2024-12-01T10:00:01.790Z abc-123 ERROR {
+    "errorType": "CustomerNotFoundError",
+    "errorMessage": "Customer CUST-789 does not exist",
+    "stackTrace": ["at getCustomer (/var/task/handler.js:25:11)"]
+  }
+  END RequestId: abc-123
+  REPORT RequestId: abc-123 Duration: 1667.45 ms
+  Billed Duration: 1668 ms Memory Size: 256 MB
+  Max Memory Used: 89 MB Init Duration: 423.12 ms
+
+  Understanding the REPORT line:
+  - Duration: actual execution time (1667.45ms)
+  - Billed Duration: rounded up for billing (1668ms)
+  - Memory Size: configured memory (256MB)
+  - Max Memory Used: peak memory during execution (89MB)
+  - Init Duration: cold start initialization time (only on cold starts)
+
+  Problem: The logs are unstructured text, making it hard to search
+  across thousands of invocations. Better approach: structured JSON
+  logging with correlation IDs.
+
+  Task: Explain CloudWatch Logs for Lambda debugging. Write: how
+  Lambda logs are organized (log groups, log streams), understanding
+  the REPORT line metrics, structured logging best practices (JSON
+  format, correlation IDs), searching logs (filter patterns, Logs
+  Insights queries), and common logging mistakes to avoid.
+
+assertions:
+  - type: llm_judge
+    criteria: "Log organization is explained — log group: /aws/lambda/<function-name> (one per function). Log streams: one per execution environment (not per invocation — multiple warm invocations share a stream). Each invocation has START, your logs, END, and REPORT markers. RequestId links all entries for one invocation. CloudWatch Logs Insights: SQL-like query language to search across streams. Example: filter @message like /ERROR/ | stats count() by bin(1h)"
+    weight: 0.35
+    description: "Log organization"
+  - type: llm_judge
+    criteria: "REPORT line and structured logging are covered — REPORT fields: Duration (actual), Billed Duration (billing), Memory Size (configured), Max Memory Used (peak, for right-sizing), Init Duration (cold start only, absent on warm). XRAY TraceId appears if tracing enabled. Structured logging: use JSON format with consistent fields (requestId, level, message, timestamp). Libraries: Powertools for AWS Lambda (Python/TypeScript/Java) provides structured logging, tracing, metrics. Include correlation IDs (orderId, customerId) for tracing business transactions"
+    weight: 0.35
+    description: "REPORT and structured logging"
+  - type: llm_judge
+    criteria: "Practical tips are included — common mistakes: logging sensitive data (PII, credentials), excessive logging (increases costs and CloudWatch charges), not setting log retention (logs stored forever by default = growing costs). Set retention policy: 7/14/30 days based on needs. Use log levels (DEBUG in dev, INFO/WARN in prod). CloudWatch Logs Insights queries are powerful: parse, filter, stats, sort. Cost awareness: CloudWatch Logs charged per GB ingested — structured logging with appropriate levels controls costs"
+    weight: 0.30
+    description: "Practical tips"

package/courses/aws-lambda-debugging/scenarios/level-1/cold-start-basics.yaml

@@ -0,0 +1,70 @@
+meta:
+  id: cold-start-basics
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda cold start issues — understand cold vs warm invocations, identify cold start impact, and apply basic optimization techniques"
+  tags: [AWS, Lambda, cold-start, performance, initialization, beginner]
+
+state: {}
+
+trigger: |
+  Users complain that your API is "sometimes slow." CloudWatch metrics
+  show the Lambda function behind API Gateway has inconsistent latency:
+
+  Most requests: 50-100ms
+  Some requests: 2,000-5,000ms (40x slower!)
+
+  CloudWatch Logs reveal the pattern:
+
+  Slow invocation (cold start):
+  INIT_START Runtime Version: nodejs20.x
+  START RequestId: abc-123
+  2024-12-01T10:00:00.000Z Connecting to database...
+  2024-12-01T10:00:01.500Z Database connected
+  2024-12-01T10:00:02.000Z Processing request...
+  END RequestId: abc-123
+  REPORT RequestId: abc-123 Duration: 2100.00 ms
+  Billed Duration: 2100 ms Init Duration: 1850.00 ms
+
+  Fast invocation (warm):
+  START RequestId: def-456
+  2024-12-01T10:01:00.000Z Processing request...
+  END RequestId: def-456
+  REPORT RequestId: def-456 Duration: 55.00 ms
+  Billed Duration: 56 ms
+
+  The key difference: "Init Duration" appears only on cold starts.
+  This is the time Lambda takes to:
+  1. Download your code package
+  2. Start the runtime (Node.js/Python/Java)
+  3. Run initialization code (imports, DB connections, SDK setup)
+
+  After a cold start, the execution environment is reused for
+  subsequent invocations (warm starts) — no Init Duration.
+
+  Cold starts happen when:
+  - First invocation after deployment
+  - Scaling up (new concurrent executions)
+  - After ~15 minutes of inactivity (environment recycled)
+
+  Task: Explain Lambda cold starts. Write: what causes cold starts,
+  how to identify them in logs (INIT_START, Init Duration in REPORT),
+  factors affecting cold start duration (package size, runtime,
+  memory, VPC), basic optimizations (minimize dependencies, increase
+  memory, init code outside handler), and when cold starts matter
+  vs when they don't.
+
+assertions:
+  - type: llm_judge
+    criteria: "Cold start mechanics are explained — cold start = Lambda creates new execution environment (download code, start runtime, run init). Identified by: INIT_START in logs, Init Duration in REPORT line. Warm start reuses existing environment — no init overhead. Cold starts happen: first invocation, scaling up new instances, after idle timeout (~15 min). Factors: package size (larger = slower download), runtime (Java/C# slowest, Python/Node fastest), memory setting (more memory = more CPU = faster init), VPC adds ENI attachment time"
+    weight: 0.35
+    description: "Cold start mechanics"
+  - type: llm_judge
+    criteria: "Basic optimizations are covered — minimize package size: remove unused dependencies, use tree shaking, use Lambda layers for shared code. Increase memory: Lambda allocates CPU proportional to memory — 1769MB = 1 vCPU. Higher memory = faster initialization. Init code outside handler: database connections, SDK clients created at module level are reused across warm invocations. Avoid importing unused modules. For critical latency: provisioned concurrency keeps environments warm (eliminates cold starts entirely)"
+    weight: 0.35
+    description: "Basic optimizations"
+  - type: llm_judge
+    criteria: "When cold starts matter is explained — matters: synchronous APIs (user-facing latency), real-time processing. Doesn't matter: async processing (SQS consumers, S3 events), batch jobs, scheduled tasks. Cold start frequency: at steady traffic with consistent load, most invocations are warm. Spiky traffic causes more cold starts. Monitor: CloudWatch metric ConcurrentExecutions shows scaling events. p99 latency includes cold starts, p50 typically doesn't. Evaluate whether cold start optimization is worth the effort based on actual user impact"
+    weight: 0.30
+    description: "When it matters"

package/courses/aws-lambda-debugging/scenarios/level-1/environment-variable-issues.yaml

@@ -0,0 +1,72 @@
+meta:
+  id: environment-variable-issues
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda environment variable issues — diagnose missing, incorrect, or encrypted environment variables and configuration problems"
+  tags: [AWS, Lambda, environment-variables, configuration, KMS, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function fails with a connection error:
+
+  {
+    "errorType": "Error",
+    "errorMessage": "connect ECONNREFUSED 127.0.0.1:5432"
+  }
+
+  The function tries to connect to a database but the connection
+  string is wrong. Checking the code:
+
+  const dbHost = process.env.DATABASE_URL;
+  // dbHost is undefined!
+
+  The environment variable is named DB_URL in the Lambda configuration
+  but the code expects DATABASE_URL. Classic mismatch.
+
+  $ aws lambda get-function-configuration --function-name my-func \
+    --query "Environment.Variables"
+  {
+    "DB_URL": "postgresql://prod-db.example.com:5432/mydb",
+    "API_KEY": "sk-prod-abc123..."
+  }
+
+  Issues found:
+
+  1. Variable name mismatch — DB_URL vs DATABASE_URL. Case-sensitive.
+
+  2. API_KEY is stored as plain text in the Lambda configuration.
+     Anyone with lambda:GetFunctionConfiguration permission can see
+     it. Should use AWS Secrets Manager or encrypted env vars.
+
+  3. After fixing the name, the function still fails in a new
+     deployment. The developer tested with staging env vars but
+     deployed to production without updating them. No environment-
+     specific configuration management.
+
+  4. Environment variables have a 4KB total size limit. A function
+     with many config values hits this limit:
+     "InvalidParameterValueException: Lambda was unable to configure
+     your environment variables because the environment variables you
+     have provided exceeded the 4KB limit."
+
+  Task: Explain Lambda environment variable debugging. Write: how to
+  check and set environment variables (CLI, console, IaC), common
+  mistakes (name mismatches, case sensitivity), encryption with KMS,
+  the 4KB limit and alternatives (Secrets Manager, Parameter Store,
+  S3), and environment management across stages.
+
+assertions:
+  - type: llm_judge
+    criteria: "Environment variable basics are explained — env vars set via console, CLI (aws lambda update-function-configuration --environment), or IaC (SAM/CDK/Terraform). Variables are key-value strings, case-sensitive. Available via process.env (Node.js), os.environ (Python), System.getenv (Java). Common errors: name mismatch between code and config, forgetting to set in new deployments, using wrong values for the environment (staging vs production). Variables are set at deploy time, not runtime"
+    weight: 0.35
+    description: "Environment variable basics"
+  - type: llm_judge
+    criteria: "Security and limits are covered — env vars visible to anyone with lambda:GetFunctionConfiguration permission. Sensitive values: use AWS Secrets Manager (automatic rotation, cross-account access) or SSM Parameter Store (simpler, cheaper). KMS encryption: Lambda can encrypt env vars with custom KMS key — decrypted at runtime. 4KB total limit for all env vars combined. For large config: use Parameter Store (up to 8KB standard, 64KB advanced) or S3 for config files. Never put secrets in plain text env vars — use Secrets Manager"
+    weight: 0.35
+    description: "Security and limits"
+  - type: llm_judge
+    criteria: "Environment management is practical — use IaC (SAM, CDK) with environment-specific parameter files. SAM: --parameter-overrides for stage-specific values. CDK: separate stacks or context variables per environment. Never hardcode environment-specific values in code. Pattern: store environment name as env var (STAGE=prod), look up other config from Parameter Store using STAGE prefix. Validate required env vars at function initialization (fail fast if missing). Use .env files for local development (SAM local supports --env-vars)"
+    weight: 0.30
+    description: "Environment management"

package/courses/aws-lambda-debugging/scenarios/level-1/first-debugging-shift.yaml

@@ -0,0 +1,73 @@
+meta:
+  id: first-debugging-shift
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Combined first debugging shift — diagnose a Lambda-based API with timeout, permission, memory, and configuration issues simultaneously"
+  tags: [AWS, Lambda, troubleshooting, combined, shift-simulation, beginner]
+
+state: {}
+
+trigger: |
+  You've joined a team that has a serverless API with 4 Lambda
+  functions behind API Gateway. "The API is broken" — users report
+  various errors. You need to triage everything:
+
+  $ curl https://api.example.com/orders
+  → 502 Bad Gateway
+
+  $ curl https://api.example.com/users
+  → 504 Gateway Timeout (after 29 seconds)
+
+  $ curl https://api.example.com/products
+  → 403 {"message": "Forbidden"}
+
+  $ curl https://api.example.com/payments
+  → 200 but returns empty data instead of payment records
+
+  Investigation:
+
+  1. /orders → 502: Lambda returns malformed response.
+     CloudWatch Logs: function returns {body: orders} without
+     statusCode and body is not a string. Fix: proper proxy
+     integration response format.
+
+  2. /users → 504: Lambda times out.
+     REPORT: Duration 29001ms, timeout is 30s. Function connects
+     to RDS in VPC but has no NAT Gateway for the Secrets Manager
+     call that retrieves the DB password. The Secrets Manager call
+     hangs because there's no internet access from the private subnet.
+     Fix: add VPC endpoint for Secrets Manager, or add NAT Gateway.
+
+  3. /products → 403: API key required but not sent.
+     API Gateway has "API Key Required: true" on this method but
+     documentation doesn't mention it. The API key is correct in
+     the x-api-key header. Fix: send the API key header, or remove
+     the API key requirement if it's unintended.
+
+  4. /payments → 200 but empty: Lambda runs successfully but
+     DynamoDB query returns no items. The function reads from
+     table "Payments" but the actual table is "payments-prod"
+     (different name). The IAM role has permission on "payments-prod"
+     but the code hardcodes "Payments". Fix: use environment variable
+     for table name, update code to match actual table.
+
+  Task: Walk through diagnosing all four issues. Write: the triage
+  approach (check HTTP status codes, then CloudWatch Logs), how
+  to debug each error type, the VPC Lambda networking gotcha,
+  API Gateway configuration checks, and lessons learned for
+  preventing these issues.
+
+assertions:
+  - type: llm_judge
+    criteria: "All four issues are diagnosed — (1) 502 malformed response: fix Lambda proxy response format (statusCode, string body). (2) 504 timeout: VPC Lambda needs NAT Gateway or VPC endpoints for AWS service access. (3) 403 API key: check API Gateway method settings for required API key, send x-api-key header. (4) 200 empty data: code references wrong DynamoDB table name — use environment variables for resource names, not hardcoded strings"
+    weight: 0.35
+    description: "All issues diagnosed"
+  - type: llm_judge
+    criteria: "Triage methodology is systematic — start with HTTP status code (tells error category: 4xx client, 5xx server). Check API Gateway logs first (shows if error is in API GW config or Lambda). Then check Lambda CloudWatch Logs for each function. Read the REPORT line for timeout/memory issues. Check IAM for permission issues. Check VPC configuration for networking issues. Work through issues by severity: 502/504 first (service down), then 403 (auth), then data issues"
+    weight: 0.35
+    description: "Triage methodology"
+  - type: llm_judge
+    criteria: "Prevention lessons are practical — use IaC (SAM/CDK) for consistent configuration. Use environment variables for all resource names (table names, queue URLs, bucket names). Test Lambda responses match API Gateway proxy format before deploying. For VPC Lambda: always plan networking (NAT Gateway or VPC endpoints for AWS services). Document API requirements (API keys, auth). Use local testing (SAM CLI) to catch errors before deployment. Set up CloudWatch alarms for Errors, Throttles, Duration"
+    weight: 0.30
+    description: "Prevention lessons"

package/courses/aws-lambda-debugging/scenarios/level-1/handler-import-errors.yaml

@@ -0,0 +1,71 @@
+meta:
+  id: handler-import-errors
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda handler and import errors — diagnose module not found, handler not found, and dependency packaging issues"
+  tags: [AWS, Lambda, handler, import, module-not-found, packaging, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function fails immediately on invocation:
+
+  {
+    "errorType": "Runtime.ImportModuleError",
+    "errorMessage": "Unable to import module 'handler': No module named 'requests'"
+  }
+
+  The function works locally but fails in Lambda. The issue: the
+  'requests' library isn't included in the deployment package.
+
+  Lambda runtimes only include standard library modules. Third-party
+  dependencies must be packaged with your code:
+
+  # Python — create deployment package with dependencies:
+  pip install requests -t ./package/
+  cd package && zip -r ../deployment.zip . && cd ..
+  zip deployment.zip handler.py
+
+  Another common error:
+  {
+    "errorType": "Runtime.HandlerNotFound",
+    "errorMessage": "Handler 'app.handler' missing on module 'app'"
+  }
+
+  Causes:
+  1. Wrong handler configuration — Lambda handler format is file.function
+     (Python: handler.lambda_handler, Node: index.handler)
+  2. File is in a subdirectory but handler doesn't include the path
+     (src/handler.lambda_handler won't work — zip must have handler.py
+     at the root)
+  3. Typo in function name
+
+  Node.js variant:
+  {
+    "errorType": "Runtime.UserCodeSyntaxError",
+    "errorMessage": "SyntaxError: Cannot use import statement outside a module"
+  }
+
+  Using ES modules (import/export) requires either:
+  - File extension .mjs, or
+  - "type": "module" in package.json
+
+  Task: Explain Lambda handler and import debugging. Write: the handler
+  format for each runtime (Python, Node.js, Java), common import/module
+  errors and their causes, how to package dependencies correctly (zip,
+  layers, container images), and the deployment package structure.
+
+assertions:
+  - type: llm_judge
+    criteria: "Handler format is explained — Python: file_name.function_name (e.g., handler.lambda_handler). Node.js: file_name.export_name (e.g., index.handler). Java: package.Class::method. The handler file must be at the root of the zip or in the path specified. Runtime.HandlerNotFound: file or function doesn't exist at the expected location. Runtime.ImportModuleError: dependency not included in package. Always test with lambda invoke locally (SAM CLI) before deploying"
+    weight: 0.35
+    description: "Handler format"
+  - type: llm_judge
+    criteria: "Dependency packaging is covered — Python: pip install -t ./package/, include in zip. Use requirements.txt. Node.js: npm install in project, zip node_modules with code. Lambda Layers: shared dependencies across functions (up to 5 layers, 250MB unzipped total). Container images: full control over runtime and dependencies (up to 10GB). Common mistakes: installing for wrong OS (Lambda runs Amazon Linux — build on Linux or use Docker), missing native modules (needs compilation for Lambda architecture: x86_64 or arm64)"
+    weight: 0.35
+    description: "Dependency packaging"
+  - type: llm_judge
+    criteria: "Debugging workflow is practical — check CloudWatch Logs first (error type tells you the category). Runtime.ImportModuleError: dependency missing from package or layer. Runtime.HandlerNotFound: wrong handler config or file structure. Runtime.UserCodeSyntaxError: code syntax issue (ESM vs CJS for Node.js). Test locally: AWS SAM CLI (sam local invoke) simulates Lambda environment. Check package structure: unzip -l deployment.zip to verify file locations. Verify architecture: Lambda ARM (Graviton2) needs arm64 native dependencies"
+    weight: 0.30
+    description: "Debugging workflow"

package/courses/aws-lambda-debugging/scenarios/level-1/iam-permission-errors.yaml

@@ -0,0 +1,68 @@
+meta:
+  id: iam-permission-errors
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda IAM permission errors — diagnose AccessDenied errors from missing or incorrect IAM policies"
+  tags: [AWS, Lambda, IAM, permissions, AccessDenied, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function fails when trying to read from S3:
+
+  {
+    "errorType": "AccessDeniedException",
+    "errorMessage": "User: arn:aws:sts::123456789012:assumed-role/
+    process-order-role/process-order is not authorized to perform:
+    s3:GetObject on resource: arn:aws:s3:::my-bucket/orders/*"
+  }
+
+  The error clearly states what's missing: s3:GetObject permission on
+  the specific S3 bucket and path.
+
+  Checking the Lambda's execution role:
+  $ aws iam get-role --role-name process-order-role
+  $ aws iam list-attached-role-policies --role-name process-order-role
+
+  The role only has AWSLambdaBasicExecutionRole (CloudWatch Logs).
+  It needs an additional policy for S3 access.
+
+  Fix:
+  $ aws iam put-role-policy --role-name process-order-role \
+    --policy-name S3ReadAccess \
+    --policy-document '{
+      "Version": "2012-10-17",
+      "Statement": [{
+        "Effect": "Allow",
+        "Action": "s3:GetObject",
+        "Resource": "arn:aws:s3:::my-bucket/orders/*"
+      }]
+    }'
+
+  Common IAM mistakes with Lambda:
+  1. Using s3:* instead of specific actions (security risk)
+  2. Using Resource: "*" instead of specific ARNs
+  3. Forgetting that Lambda needs TWO types of permissions:
+     - Execution role: what the function CAN DO (call S3, DynamoDB)
+     - Resource policy: who can INVOKE the function (API GW, S3 events)
+  4. Policy changes take a few seconds to propagate
+
+  Task: Explain Lambda IAM debugging. Write: how to read AccessDenied
+  errors (they tell you exactly what's missing), the execution role
+  vs resource policy distinction, principle of least privilege for
+  Lambda, common IAM mistakes, and how to test permissions.
+
+assertions:
+  - type: llm_judge
+    criteria: "IAM error reading is explained — AccessDenied errors include: the principal (Lambda execution role ARN), the action attempted (s3:GetObject), and the resource ARN. This tells you exactly what permission to add. Two permission types: execution role (attached IAM role — what Lambda can do: read S3, write DynamoDB, publish SNS) and resource-based policy (who can invoke Lambda: API Gateway, S3 event notifications, CloudWatch Events). Both must be correct"
+    weight: 0.35
+    description: "IAM error reading"
+  - type: llm_judge
+    criteria: "Common mistakes and fixes are covered — overly broad permissions (s3:* on Resource: * is dangerous). Always specify exact actions and resource ARNs. Forgetting to add AWSLambdaBasicExecutionRole (needed for CloudWatch Logs). VPC Lambda needs AWSLambdaVPCAccessExecutionRole. Policy propagation delay (wait a few seconds after policy changes). KMS permissions needed when using encrypted resources. Cross-account access requires both resource policy and execution role permissions"
+    weight: 0.35
+    description: "Common mistakes"
+  - type: llm_judge
+    criteria: "Testing and best practices are practical — test permissions: aws iam simulate-principal-policy. Use AWS IAM Access Analyzer to identify overly permissive policies. Start with no permissions, add as needed (least privilege). Use managed policies for common patterns (AmazonDynamoDBReadOnlyAccess). CloudTrail logs every API call — search for AccessDenied events. Use IAM policy conditions for additional security (restrict by source IP, time, VPC). Tag Lambda roles for identification"
+    weight: 0.30
+    description: "Testing and practices"

package/courses/aws-lambda-debugging/scenarios/level-1/invocation-errors.yaml

@@ -0,0 +1,72 @@
+meta:
+  id: invocation-errors
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda invocation errors — diagnose throttling, concurrency limits, and invocation type differences (sync vs async)"
+  tags: [AWS, Lambda, invocation, throttling, concurrency, sync-async, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function starts returning errors during a traffic spike:
+
+  $ aws lambda invoke --function-name process-order output.json
+  {
+    "StatusCode": 429,
+    "FunctionError": "Unhandled"
+  }
+
+  $ cat output.json
+  {
+    "errorType": "TooManyRequestsException",
+    "errorMessage": "Rate exceeded"
+  }
+
+  CloudWatch metrics show:
+  - Throttles: 1,500 (these are rejected requests!)
+  - ConcurrentExecutions: 1,000 (account limit)
+  - Errors: 200 (actual function errors)
+  - Invocations: 8,300
+
+  The account has a default concurrency limit of 1,000 across ALL
+  Lambda functions. Your function is consuming 800 concurrent
+  executions, starving other functions.
+
+  Important: Throttles are NOT counted in Invocations or Errors
+  metrics! You must monitor the Throttles metric separately.
+
+  Understanding invocation types:
+
+  Synchronous (RequestResponse):
+  - API Gateway, CLI invoke, SDK invoke
+  - Caller waits for response
+  - Throttled: returns 429 immediately
+  - Errors: returned to caller
+
+  Asynchronous (Event):
+  - S3 events, SNS, EventBridge
+  - Caller gets 202 Accepted immediately
+  - Lambda retries twice on failure
+  - Throttled: Lambda retries with backoff for up to 6 hours
+  - Failed after retries: sent to DLQ or destination
+
+  Task: Explain Lambda invocation debugging. Write: synchronous vs
+  asynchronous invocation differences, throttling (what it is, how
+  to detect, how to fix), concurrency limits (account vs function
+  reserved), the retry behavior for each invocation type, and how
+  to monitor invocation health.
+
+assertions:
+  - type: llm_judge
+    criteria: "Invocation types are explained — synchronous: caller waits, gets response or error. Used by API Gateway, CLI, SDK. Asynchronous: caller gets 202 immediately, Lambda processes in background. Used by S3, SNS, EventBridge. Lambda retries async failures twice (3 total attempts). Poll-based: Lambda polls event source (SQS, Kinesis, DynamoDB Streams) — behaves differently for each. Understanding invocation type is critical because error handling, retry behavior, and throttling behavior differ for each"
+    weight: 0.35
+    description: "Invocation types"
+  - type: llm_judge
+    criteria: "Throttling and concurrency are covered — default account limit: 1,000 concurrent executions (can be increased via support). Throttling = requests rejected when concurrency limit reached. Throttles metric: must monitor separately (not counted in Invocations or Errors!). Reserved concurrency: guarantee capacity for a function (but limits it too). Provisioned concurrency: pre-warm environments for consistent latency. Fix throttling: request limit increase, use reserved concurrency to protect critical functions, implement backoff in callers, use SQS to buffer requests"
+    weight: 0.35
+    description: "Throttling and concurrency"
+  - type: llm_judge
+    criteria: "Monitoring and retry behavior are practical — monitor: Invocations, Errors, Throttles, Duration, ConcurrentExecutions. Set alarms on: Throttles > 0, Error rate > 5%, Duration approaching timeout. Retry behavior: sync — no automatic retry (caller must retry), async — 2 retries with exponential backoff, then DLQ/destination. SQS: retries based on visibility timeout, then DLQ. Kinesis/DynamoDB Streams: retries until record expires or succeeds (can block shard). Configure maxRetryAttempts and DLQ for each invocation pattern"
+    weight: 0.30
+    description: "Monitoring and retry"

package/courses/aws-lambda-debugging/scenarios/level-1/lambda-timeout-errors.yaml

@@ -0,0 +1,65 @@
+meta:
+  id: lambda-timeout-errors
+  level: 1
+  course: aws-lambda-debugging
+  type: output
+  description: "Debug Lambda timeout errors — diagnose why functions exceed their configured timeout and how to fix common timeout causes"
+  tags: [AWS, Lambda, timeout, duration, configuration, beginner]
+
+state: {}
+
+trigger: |
+  Your Lambda function fails with a timeout error:
+
+  $ aws lambda invoke --function-name process-order output.json
+  {
+    "StatusCode": 200,
+    "FunctionError": "Unhandled",
+    "ExecutedVersion": "$LATEST"
+  }
+
+  $ cat output.json
+  {
+    "errorMessage": "2024-12-01T10:00:00.000Z abc-123 Task timed out after 3.00 seconds"
+  }
+
+  CloudWatch Logs:
+  START RequestId: abc-123 Version: $LATEST
+  2024-12-01T10:00:00.000Z abc-123 Connecting to database...
+  2024-12-01T10:00:03.000Z abc-123 Task timed out after 3.00 seconds
+  END RequestId: abc-123
+  REPORT RequestId: abc-123 Duration: 3001.45 ms
+  Billed Duration: 3000 ms Memory Size: 128 MB Max Memory Used: 65 MB
+
+  The function has a 3-second timeout (default) but the database
+  connection takes 4+ seconds on cold start. The function never
+  reaches the actual business logic.
+
+  Fix options:
+  1. Increase timeout: aws lambda update-function-configuration \
+       --function-name process-order --timeout 30
+  2. Optimize: connection pooling, move DB connection outside handler
+  3. Use RDS Proxy for faster connection establishment
+
+  But setting timeout too high is also a problem — if the function
+  hangs, you pay for the full duration (max 15 minutes).
+
+  Task: Explain Lambda timeout debugging. Write: what the timeout
+  error means, how to read the REPORT line (Duration, Billed Duration,
+  Memory), common timeout causes (DB connections, API calls, large
+  payloads), how to set appropriate timeouts, and the relationship
+  between Lambda timeout and API Gateway timeout (29 seconds max).
+
+assertions:
+  - type: llm_judge
+    criteria: "Timeout mechanics are explained — Lambda timeout is configurable (default 3 seconds, max 15 minutes). When exceeded, Lambda kills the execution and returns a Task timed out error. The REPORT line shows: Duration (actual execution time), Billed Duration (rounded up to nearest ms or 1ms minimum), Memory Size (configured), Max Memory Used (peak). Billed for full timeout duration if it times out. CloudWatch Logs show what happened before timeout"
+    weight: 0.35
+    description: "Timeout mechanics"
+  - type: llm_judge
+    criteria: "Common causes and fixes are covered — database connections on cold start (use connection pooling, RDS Proxy, initialize outside handler for reuse), external API calls without timeout (always set HTTP timeout shorter than Lambda timeout), large S3 file processing (stream instead of loading entirely into memory), cold start initialization (heavy imports, large packages). Set Lambda timeout slightly higher than expected max duration. API Gateway has a hard 29-second limit — Lambda behind API GW must complete within 29s"
+    weight: 0.35
+    description: "Causes and fixes"
+  - type: llm_judge
+    criteria: "Best practices are practical — set timeout based on p99 duration + buffer (not arbitrary large values). Monitor with CloudWatch Duration metric. Alert when duration approaches timeout. Use X-Ray to identify slow segments. Move initialization code outside handler (runs once per cold start, reused on warm invocations). Set HTTP client timeouts shorter than Lambda timeout to get a proper error instead of Lambda timeout. For long-running tasks: use Step Functions, SQS, or async invocation instead of increasing Lambda timeout"
+    weight: 0.30
+    description: "Best practices"