aigroup-workflow 2.1.1 → 2.2.0

package/skills/infra/terraform-engineer/references/testing.md

@@ -0,0 +1,486 @@
+# Terraform Testing Strategies
+
+## Terraform Plan Validation
+
+**Basic Plan Workflow**
+```bash
+# Initialize and validate syntax
+terraform init
+terraform fmt -check
+terraform validate
+
+# Plan with output
+terraform plan -out=tfplan
+
+# Show plan in JSON for automated review
+terraform show -json tfplan | jq .
+
+# Apply specific plan
+terraform apply tfplan
+```
+
+**Plan with Variable Files**
+```bash
+# Plan with specific tfvars
+terraform plan -var-file="production.tfvars"
+
+# Plan with inline variables
+terraform plan -var="instance_count=5"
+
+# Plan with multiple var files
+terraform plan \
+  -var-file="common.tfvars" \
+  -var-file="production.tfvars"
+```
+
+**Plan Analysis**
+```bash
+# Resource targeting for specific resources
+terraform plan -target=aws_vpc.main
+
+# Refresh only (check drift)
+terraform plan -refresh-only
+
+# Destroy plan
+terraform plan -destroy
+
+# Save plan output
+terraform plan -out=tfplan 2>&1 | tee plan-output.txt
+```
+
+## Terraform Test (1.6+)
+
+**Test File Structure**
+```
+tests/
+├── unit/
+│   ├── vpc_test.tftest.hcl
+│   └── security_group_test.tftest.hcl
+└── integration/
+    └── complete_test.tftest.hcl
+```
+
+**Basic Test**
+```hcl
+# tests/vpc_test.tftest.hcl
+run "validate_vpc_cidr" {
+  command = plan
+
+  variables {
+    cidr_block = "10.0.0.0/16"
+    name       = "test-vpc"
+  }
+
+  assert {
+    condition     = aws_vpc.main.cidr_block == "10.0.0.0/16"
+    error_message = "VPC CIDR block did not match expected value"
+  }
+
+  assert {
+    condition     = aws_vpc.main.enable_dns_hostnames == true
+    error_message = "DNS hostnames should be enabled"
+  }
+}
+
+run "validate_tags" {
+  command = plan
+
+  variables {
+    cidr_block = "10.0.0.0/16"
+    name       = "test-vpc"
+    tags = {
+      Environment = "test"
+    }
+  }
+
+  assert {
+    condition     = aws_vpc.main.tags["Environment"] == "test"
+    error_message = "Environment tag not set correctly"
+  }
+}
+```
+
+**Integration Test**
+```hcl
+# tests/integration/complete_test.tftest.hcl
+run "create_full_stack" {
+  command = apply
+
+  variables {
+    cidr_block = "10.0.0.0/16"
+    name       = "integration-test"
+
+    private_subnets = {
+      app = { cidr_block = "10.0.1.0/24", az = "us-east-1a" }
+    }
+  }
+
+  assert {
+    condition     = length(aws_subnet.private) == 1
+    error_message = "Should create exactly one private subnet"
+  }
+
+  assert {
+    condition     = output.vpc_id != ""
+    error_message = "VPC ID should not be empty"
+  }
+}
+```
+
+**Run Tests**
+```bash
+# Run all tests
+terraform test
+
+# Run specific test file
+terraform test tests/vpc_test.tftest.hcl
+
+# Verbose output
+terraform test -verbose
+
+# Keep test resources (for debugging)
+terraform test -no-cleanup
+```
+
+## Terratest (Go-based Testing)
+
+**Test Structure**
+```
+tests/
+├── go.mod
+├── go.sum
+└── vpc_test.go
+```
+
+**go.mod**
+```go
+module github.com/example/terraform-modules/tests
+
+go 1.21
+
+require (
+    github.com/gruntwork-io/terratest v0.45.0
+    github.com/stretchr/testify v1.8.4
+)
+```
+
+**Basic Terratest**
+```go
+// tests/vpc_test.go
+package test
+
+import (
+    "testing"
+
+    "github.com/gruntwork-io/terratest/modules/terraform"
+    "github.com/stretchr/testify/assert"
+)
+
+func TestVPCCreation(t *testing.T) {
+    t.Parallel()
+
+    terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
+        TerraformDir: "../examples/complete",
+
+        Vars: map[string]interface{}{
+            "name":       "test-vpc",
+            "cidr_block": "10.0.0.0/16",
+        },
+
+        EnvVars: map[string]string{
+            "AWS_DEFAULT_REGION": "us-east-1",
+        },
+    })
+
+    defer terraform.Destroy(t, terraformOptions)
+
+    terraform.InitAndApply(t, terraformOptions)
+
+    vpcID := terraform.Output(t, terraformOptions, "vpc_id")
+    assert.NotEmpty(t, vpcID)
+
+    vpcCIDR := terraform.Output(t, terraformOptions, "vpc_cidr_block")
+    assert.Equal(t, "10.0.0.0/16", vpcCIDR)
+}
+```
+
+**Advanced Terratest with AWS SDK**
+```go
+package test
+
+import (
+    "testing"
+
+    "github.com/aws/aws-sdk-go/aws"
+    "github.com/aws/aws-sdk-go/service/ec2"
+    "github.com/gruntwork-io/terratest/modules/terraform"
+    aws_helper "github.com/gruntwork-io/terratest/modules/aws"
+    "github.com/stretchr/testify/assert"
+)
+
+func TestVPCConfiguration(t *testing.T) {
+    t.Parallel()
+
+    awsRegion := "us-east-1"
+
+    terraformOptions := &terraform.Options{
+        TerraformDir: "../examples/complete",
+        Vars: map[string]interface{}{
+            "name":       "test-vpc",
+            "cidr_block": "10.0.0.0/16",
+        },
+    }
+
+    defer terraform.Destroy(t, terraformOptions)
+    terraform.InitAndApply(t, terraformOptions)
+
+    vpcID := terraform.Output(t, terraformOptions, "vpc_id")
+
+    // Verify VPC configuration using AWS SDK
+    vpc := aws_helper.GetVpcById(t, vpcID, awsRegion)
+    assert.Equal(t, "10.0.0.0/16", *vpc.CidrBlock)
+    assert.True(t, *vpc.EnableDnsSupport)
+    assert.True(t, *vpc.EnableDnsHostnames)
+
+    // Verify tags
+    tags := convertEC2TagsToMap(vpc.Tags)
+    assert.Equal(t, "test-vpc", tags["Name"])
+}
+
+func convertEC2TagsToMap(tags []*ec2.Tag) map[string]string {
+    result := make(map[string]string)
+    for _, tag := range tags {
+        result[*tag.Key] = *tag.Value
+    }
+    return result
+}
+```
+
+**Run Terratest**
+```bash
+cd tests
+go mod download
+go test -v -timeout 30m
+```
+
+## Policy as Code - OPA/Sentinel
+
+**Open Policy Agent (OPA)**
+
+**policy.rego**
+```rego
+package terraform.analysis
+
+import input as tfplan
+
+# Deny if resources are not tagged
+deny[msg] {
+    r := tfplan.resource_changes[_]
+    r.change.actions[_] == "create"
+    not r.change.after.tags.Environment
+    msg := sprintf("Resource %s is missing Environment tag", [r.address])
+}
+
+# Require encryption for S3 buckets
+deny[msg] {
+    r := tfplan.resource_changes[_]
+    r.type == "aws_s3_bucket"
+    r.change.actions[_] == "create"
+    not r.change.after.server_side_encryption_configuration
+    msg := sprintf("S3 bucket %s must have encryption enabled", [r.address])
+}
+
+# Ensure VPC flow logs are enabled
+deny[msg] {
+    r := tfplan.resource_changes[_]
+    r.type == "aws_vpc"
+    r.change.actions[_] == "create"
+    vpc_id := r.change.after.id
+    not has_flow_log(vpc_id)
+    msg := sprintf("VPC %s must have flow logs enabled", [r.address])
+}
+
+has_flow_log(vpc_id) {
+    r := tfplan.resource_changes[_]
+    r.type == "aws_flow_log"
+    r.change.after.vpc_id == vpc_id
+}
+```
+
+**Run OPA Policy**
+```bash
+# Generate plan in JSON
+terraform plan -out=tfplan
+terraform show -json tfplan > tfplan.json
+
+# Run OPA policy check
+opa eval -i tfplan.json -d policy.rego "data.terraform.analysis.deny"
+```
+
+**Conftest (OPA wrapper for testing)**
+```bash
+# Install conftest
+brew install conftest
+
+# Test plan against policies
+conftest test tfplan.json
+
+# With specific namespace
+conftest test tfplan.json --namespace terraform.analysis
+```
+
+## TFLint
+
+**Installation and Configuration**
+```bash
+# Install tflint
+brew install tflint
+
+# Initialize tflint plugins
+tflint --init
+```
+
+**.tflint.hcl**
+```hcl
+plugin "terraform" {
+  enabled = true
+  preset  = "recommended"
+}
+
+plugin "aws" {
+  enabled = true
+  version = "0.27.0"
+  source  = "github.com/terraform-linters/tflint-ruleset-aws"
+}
+
+rule "terraform_naming_convention" {
+  enabled = true
+
+  format = "snake_case"
+}
+
+rule "terraform_required_version" {
+  enabled = true
+}
+
+rule "terraform_required_providers" {
+  enabled = true
+}
+
+rule "aws_instance_invalid_type" {
+  enabled = true
+}
+
+rule "aws_s3_bucket_encryption" {
+  enabled = true
+}
+```
+
+**Run TFLint**
+```bash
+# Run linter
+tflint
+
+# With specific config
+tflint --config=.tflint.hcl
+
+# Recursive (all subdirectories)
+tflint --recursive
+
+# Output format
+tflint --format=json
+```
+
+## Pre-commit Hooks
+
+**.pre-commit-config.yaml**
+```yaml
+repos:
+  - repo: https://github.com/antonbabenko/pre-commit-terraform
+    rev: v1.83.6
+    hooks:
+      - id: terraform_fmt
+      - id: terraform_validate
+      - id: terraform_tflint
+        args:
+          - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
+      - id: terraform_docs
+        args:
+          - --hook-config=--path-to-file=README.md
+          - --hook-config=--add-to-existing-file=true
+      - id: terraform_checkov
+        args:
+          - --args=--quiet
+          - --args=--skip-check CKV_AWS_*
+```
+
+**Setup**
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# Install hooks
+pre-commit install
+
+# Run manually
+pre-commit run -a
+```
+
+## CI/CD Pipeline Testing
+
+**GitHub Actions Example**
+```yaml
+name: Terraform Test
+
+on: [pull_request]
+
+jobs:
+  terraform-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v2
+        with:
+          terraform_version: 1.6.0
+
+      - name: Terraform Format
+        run: terraform fmt -check -recursive
+
+      - name: Terraform Init
+        run: terraform init
+
+      - name: Terraform Validate
+        run: terraform validate
+
+      - name: TFLint
+        uses: terraform-linters/setup-tflint@v3
+        with:
+          tflint_version: latest
+
+      - name: Run TFLint
+        run: tflint --recursive
+
+      - name: Terraform Test
+        run: terraform test
+
+      - name: Checkov
+        uses: bridgecrewio/checkov-action@master
+        with:
+          directory: .
+          framework: terraform
+```
+
+## Best Practices
+
+- Run `terraform validate` before every commit
+- Use `terraform test` for unit and integration tests
+- Implement policy as code for security compliance
+- Run TFLint in CI/CD pipelines
+- Use pre-commit hooks for automated checks
+- Test modules with Terratest for critical infrastructure
+- Always review plan output before apply
+- Test provider upgrades in isolated environments
+- Document test scenarios and expected outcomes
+- Automate testing in pull request workflows

package/skills/infra/websocket-engineer/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: websocket-engineer
+description: Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: api-architecture
+  triggers: WebSocket, Socket.IO, real-time communication, bidirectional messaging, pub/sub, server push, live updates, chat systems, presence tracking
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fastapi-expert, nestjs-expert, devops-engineer, monitoring-expert, security-reviewer
+---
+
+# WebSocket Engineer
+
+## Core Workflow
+
+1. **Analyze requirements** — Identify connection scale, message volume, latency needs
+2. **Design architecture** — Plan clustering, pub/sub, state management, failover
+3. **Implement** — Build WebSocket server with authentication, rooms, events
+4. **Validate locally** — Test connection handling, auth, and room behavior before scaling (e.g., `npx wscat -c ws://localhost:3000`); confirm auth rejection on missing/invalid tokens, room join/leave events, and message delivery
+5. **Scale** — Verify Redis connection and pub/sub round-trip before enabling the adapter; configure sticky sessions and confirm with test connections across multiple instances; set up load balancing
+6. **Monitor** — Track connections, latency, throughput, error rates; add alerts for connection-count spikes and error-rate thresholds
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Protocol | `references/protocol.md` | WebSocket handshake, frames, ping/pong, close codes |
+| Scaling | `references/scaling.md` | Horizontal scaling, Redis pub/sub, sticky sessions |
+| Patterns | `references/patterns.md` | Rooms, namespaces, broadcasting, acknowledgments |
+| Security | `references/security.md` | Authentication, authorization, rate limiting, CORS |
+| Alternatives | `references/alternatives.md` | SSE, long polling, when to choose WebSockets |
+
+## Code Examples
+
+### Server Setup (Socket.IO with Auth and Room Management)
+
+```js
+import { createServer } from "http";
+import { Server } from "socket.io";
+import { createAdapter } from "@socket.io/redis-adapter";
+import { createClient } from "redis";
+import jwt from "jsonwebtoken";
+
+const httpServer = createServer();
+const io = new Server(httpServer, {
+  cors: { origin: process.env.ALLOWED_ORIGIN, credentials: true },
+  pingTimeout: 20000,
+  pingInterval: 25000,
+});
+
+// Authentication middleware — runs before connection is established
+io.use((socket, next) => {
+  const token = socket.handshake.auth.token;
+  if (!token) return next(new Error("Authentication required"));
+  try {
+    socket.data.user = jwt.verify(token, process.env.JWT_SECRET);
+    next();
+  } catch {
+    next(new Error("Invalid token"));
+  }
+});
+
+// Redis adapter for horizontal scaling
+const pubClient = createClient({ url: process.env.REDIS_URL });
+const subClient = pubClient.duplicate();
+await Promise.all([pubClient.connect(), subClient.connect()]);
+io.adapter(createAdapter(pubClient, subClient));
+
+io.on("connection", (socket) => {
+  const { userId } = socket.data.user;
+  console.log(`connected: ${userId} (${socket.id})`);
+
+  // Presence: mark user online
+  pubClient.hSet("presence", userId, socket.id);
+
+  socket.on("join-room", (roomId) => {
+    socket.join(roomId);
+    socket.to(roomId).emit("user-joined", { userId });
+  });
+
+  socket.on("message", ({ roomId, text }) => {
+    io.to(roomId).emit("message", { userId, text, ts: Date.now() });
+  });
+
+  socket.on("disconnect", () => {
+    pubClient.hDel("presence", userId);
+    console.log(`disconnected: ${userId}`);
+  });
+});
+
+httpServer.listen(3000);
+```
+
+### Client-Side Reconnection with Exponential Backoff
+
+```js
+import { io } from "socket.io-client";
+
+const socket = io("wss://api.example.com", {
+  auth: { token: getAuthToken() },
+  reconnection: true,
+  reconnectionAttempts: 10,
+  reconnectionDelay: 1000,       // initial delay (ms)
+  reconnectionDelayMax: 30000,   // cap at 30 s
+  randomizationFactor: 0.5,      // jitter to avoid thundering herd
+});
+
+// Queue messages while disconnected
+let messageQueue = [];
+
+socket.on("connect", () => {
+  console.log("connected:", socket.id);
+  // Flush queued messages
+  messageQueue.forEach((msg) => socket.emit("message", msg));
+  messageQueue = [];
+});
+
+socket.on("disconnect", (reason) => {
+  console.warn("disconnected:", reason);
+  if (reason === "io server disconnect") socket.connect(); // manual reconnect
+});
+
+socket.on("connect_error", (err) => {
+  console.error("connection error:", err.message);
+});
+
+function sendMessage(roomId, text) {
+  const msg = { roomId, text };
+  if (socket.connected) {
+    socket.emit("message", msg);
+  } else {
+    messageQueue.push(msg); // buffer until reconnected
+  }
+}
+```
+
+## Constraints
+
+### MUST DO
+- Use sticky sessions for load balancing (WebSocket connections are stateful — requests must route to the same server instance)
+- Implement heartbeat/ping-pong to detect dead connections (TCP keepalive alone is insufficient)
+- Use rooms/namespaces for message scoping rather than filtering in application logic
+- Queue messages during disconnection windows to avoid silent data loss
+- Plan connection limits per instance before scaling horizontally
+
+### MUST NOT DO
+- Store large state in memory without a clustering strategy (use Redis or an external store)
+- Mix WebSocket and HTTP on the same port without explicit upgrade handling
+- Forget to handle connection cleanup (presence records, room membership, in-flight timers)
+- Skip load testing before production — connection-count spikes behave differently from HTTP traffic spikes
+
+## Output Templates
+
+When implementing WebSocket features, provide:
+1. Server setup (Socket.IO/ws configuration)
+2. Event handlers (connection, message, disconnect)
+3. Client library (connection, events, reconnection)
+4. Brief explanation of scaling strategy
+
+## Knowledge Reference
+
+Socket.IO, ws, uWebSockets.js, Redis adapter, sticky sessions, nginx WebSocket proxy, JWT over WebSocket, rooms/namespaces, acknowledgments, binary data, compression, heartbeat, backpressure, horizontal pod autoscaling