Merge branch 'main' into fix/1444

Merge PR #1651: feat: add WebSocket load testing infrastructure (#1505)

.gitea/workflows/auto-assign-reviewers.yml

@@ -0,0 +1,160 @@
+# .gitea/workflows/auto-assign-reviewers.yml
+# Automated reviewer assignment for PRs
+# Issue #1444: policy: Implement automated reviewer assignment
+
+name: Auto-Assign Reviewers
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review]
+
+jobs:
+  auto-assign:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      
+      - name: Auto-assign reviewers
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+        run: |
+          echo "Auto-assigning reviewers for PR #$PR_NUMBER"
+          echo "Repository: $REPO"
+          echo "PR Author: $PR_AUTHOR"
+          
+          # Get repository name
+          REPO_NAME=$(basename "$REPO")
+          
+          # Define default reviewers based on repository
+          case "$REPO_NAME" in
+            "hermes-agent")
+              DEFAULT_REVIEWERS=("Timmy" "perplexity")
+              REQUIRED_REVIEWERS=("Timmy")
+              ;;
+            "the-nexus")
+              DEFAULT_REVIEWERS=("perplexity")
+              REQUIRED_REVIEWERS=()
+              ;;
+            "timmy-home")
+              DEFAULT_REVIEWERS=("perplexity")
+              REQUIRED_REVIEWERS=()
+              ;;
+            "timmy-config")
+              DEFAULT_REVIEWERS=("perplexity")
+              REQUIRED_REVIEWERS=()
+              ;;
+            *)
+              DEFAULT_REVIEWERS=("perplexity")
+              REQUIRED_REVIEWERS=()
+              ;;
+          esac
+          
+          # Combine default and required reviewers
+          ALL_REVIEWERS=("${DEFAULT_REVIEWERS[@]}" "${REQUIRED_REVIEWERS[@]}")
+          
+          # Remove duplicates
+          UNIQUE_REVIEWERS=($(echo "${ALL_REVIEWERS[@]}" | tr ' ' '\n' | sort -u | tr '\n' ' '))
+          
+          # Remove PR author from reviewers (can't review own PR)
+          FINAL_REVIEWERS=()
+          for reviewer in "${UNIQUE_REVIEWERS[@]}"; do
+            if [ "$reviewer" != "$PR_AUTHOR" ]; then
+              FINAL_REVIEWERS+=("$reviewer")
+            fi
+          done
+          
+          # Check if we have any reviewers
+          if [ ${#FINAL_REVIEWERS[@]} -eq 0 ]; then
+            echo "⚠️ WARNING: No reviewers available (author is only reviewer)"
+            echo "Adding fallback reviewer: perplexity"
+            FINAL_REVIEWERS=("perplexity")
+          fi
+          
+          echo "Assigning reviewers: ${FINAL_REVIEWERS[*]}"
+          
+          # Assign reviewers via Gitea API
+          for reviewer in "${FINAL_REVIEWERS[@]}"; do
+            echo "Assigning $reviewer as reviewer..."
+            
+            # Use Gitea API to request reviewer
+            RESPONSE=$(curl -s -w "%{http_code}" -X POST \
+              "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
+              -H "Authorization: token $GITEA_TOKEN" \
+              -H "Content-Type: application/json" \
+              -d "{\"reviewers\": [\"$reviewer\"]}")
+            
+            HTTP_CODE="${RESPONSE: -3}"
+            RESPONSE_BODY="${RESPONSE:0:${#RESPONSE}-3}"
+            
+            if [ "$HTTP_CODE" -eq 201 ]; then
+              echo "✅ Successfully assigned $reviewer as reviewer"
+            elif [ "$HTTP_CODE" -eq 422 ]; then
+              echo "⚠️ $reviewer is already a reviewer or cannot be assigned"
+            else
+              echo "❌ Failed to assign $reviewer (HTTP $HTTP_CODE): $RESPONSE_BODY"
+            fi
+          done
+          
+          # Verify at least one reviewer was assigned
+          echo ""
+          echo "Checking assigned reviewers..."
+          
+          REVIEWERS_RESPONSE=$(curl -s \
+            "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
+            -H "Authorization: token $GITEA_TOKEN")
+          
+          REVIEWER_COUNT=$(echo "$REVIEWERS_RESPONSE" | jq '.users | length' 2>/dev/null || echo "0")
+          
+          if [ "$REVIEWER_COUNT" -gt 0 ]; then
+            echo "✅ PR #$PR_NUMBER has $REVIEWER_COUNT reviewer(s) assigned"
+            echo "$REVIEWERS_RESPONSE" | jq '.users[].login' 2>/dev/null || echo "$REVIEWERS_RESPONSE"
+          else
+            echo "❌ ERROR: No reviewers assigned to PR #$PR_NUMBER"
+            exit 1
+          fi
+      
+      - name: Add comment about reviewer assignment
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          # Get assigned reviewers
+          REVIEWERS_RESPONSE=$(curl -s \
+            "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
+            -H "Authorization: token $GITEA_TOKEN")
+          
+          REVIEWER_LIST=$(echo "$REVIEWERS_RESPONSE" | jq -r '.users[].login' 2>/dev/null | tr '\n' ', ' | sed 's/,$//')
+          
+          if [ -n "$REVIEWER_LIST" ]; then
+            COMMENT="## Automated Reviewer Assignment
+            
+            Reviewers have been automatically assigned to this PR:
+            
+            **Assigned Reviewers:** $REVIEWER_LIST
+            
+            **Policy:** All PRs must have at least one reviewer assigned before merging.
+            
+            **Next Steps:**
+            1. Reviewers will be notified automatically
+            2. Please review the changes within 48 hours
+            3. Request changes or approve as appropriate
+            
+            This is an automated assignment based on CODEOWNERS and repository policy.
+            See issue #1444 for details."
+            
+            # Add comment to PR
+            curl -s -X POST \
+              "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/issues/$PR_NUMBER/comments" \
+              -H "Authorization: token $GITEA_TOKEN" \
+              -H "Content-Type: application/json" \
+              -d "{\"body\": \"$COMMENT\"}" > /dev/null
+            
+            echo "✅ Added comment about reviewer assignment"
+          fi

.github/CODEOWNERS

@@ -12,21 +12,8 @@ the-nexus/ai/ @Timmy
 timmy-home/ @perplexity
 timmy-config/ @perplexity
 
-# Owner gates
+# Owner gates for critical systems
 hermes-agent/ @Timmy
-# CODEOWNERS - Mandatory Review Policy
 
-# Default reviewer for all repositories
+# QA reviewer for all PRs
 * @perplexity
-
-# Specialized component owners
-hermes-agent/ @Timmy
-hermes-agent/agent-core/ @Rockachopa
-hermes-agent/protocol/ @Timmy
-the-nexus/ @perplexity
-the-nexus/ai/ @Timmy
-timmy-home/ @perplexity
-timmy-config/ @perplexity
-
-# Owner gates
-hermes-agent/ @Timmy

bin/check_reviewers.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+Check for PRs without assigned reviewers.
+Issue #1444: policy: Implement automated reviewer assignment
+"""
+
+import json
+import os
+import sys
+import urllib.request
+from typing import Dict, List, Any, Optional
+
+# Configuration
+GITEA_BASE = "https://forge.alexanderwhitestone.com/api/v1"
+TOKEN_PATH = os.path.expanduser("~/.config/gitea/token")
+ORG = "Timmy_Foundation"
+
+class ReviewerChecker:
+    def __init__(self):
+        self.token = self._load_token()
+        
+    def _load_token(self) -> str:
+        """Load Gitea API token."""
+        try:
+            with open(TOKEN_PATH, "r") as f:
+                return f.read().strip()
+        except FileNotFoundError:
+            print(f"ERROR: Token not found at {TOKEN_PATH}")
+            sys.exit(1)
+    
+    def _api_request(self, endpoint: str) -> Any:
+        """Make authenticated Gitea API request."""
+        url = f"{GITEA_BASE}{endpoint}"
+        headers = {"Authorization": f"token {self.token}"}
+        
+        req = urllib.request.Request(url, headers=headers)
+        
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return None
+            error_body = e.read().decode() if e.fp else "No error body"
+            print(f"API Error {e.code}: {error_body}")
+            return None
+    
+    def get_open_prs(self, repo: str) -> List[Dict]:
+        """Get open PRs for a repository."""
+        endpoint = f"/repos/{ORG}/{repo}/pulls?state=open"
+        prs = self._api_request(endpoint)
+        return prs if isinstance(prs, list) else []
+    
+    def get_pr_reviewers(self, repo: str, pr_number: int) -> Dict:
+        """Get requested reviewers for a PR."""
+        endpoint = f"/repos/{ORG}/{repo}/pulls/{pr_number}/requested_reviewers"
+        return self._api_request(endpoint) or {}
+    
+    def get_pr_reviews(self, repo: str, pr_number: int) -> List[Dict]:
+        """Get reviews for a PR."""
+        endpoint = f"/repos/{ORG}/{repo}/pulls/{pr_number}/reviews"
+        reviews = self._api_request(endpoint)
+        return reviews if isinstance(reviews, list) else []
+    
+    def check_prs_without_reviewers(self, repos: List[str]) -> Dict[str, Any]:
+        """Check for PRs without assigned reviewers."""
+        results = {
+            "repos": {},
+            "summary": {
+                "total_prs": 0,
+                "prs_without_reviewers": 0,
+                "repos_checked": len(repos)
+            }
+        }
+        
+        for repo in repos:
+            prs = self.get_open_prs(repo)
+            results["repos"][repo] = {
+                "total_prs": len(prs),
+                "prs_without_reviewers": [],
+                "prs_with_reviewers": []
+            }
+            results["summary"]["total_prs"] += len(prs)
+            
+            for pr in prs:
+                pr_number = pr["number"]
+                pr_title = pr["title"]
+                pr_author = pr["user"]["login"]
+                
+                # Check for requested reviewers
+                requested = self.get_pr_reviewers(repo, pr_number)
+                has_requested = len(requested.get("users", [])) > 0
+                
+                # Check for existing reviews
+                reviews = self.get_pr_reviews(repo, pr_number)
+                has_reviews = len(reviews) > 0
+                
+                # Check if author is the only potential reviewer
+                is_self_review = pr_author in [r.get("user", {}).get("login") for r in reviews]
+                
+                if not has_requested and not has_reviews:
+                    results["repos"][repo]["prs_without_reviewers"].append({
+                        "number": pr_number,
+                        "title": pr_title,
+                        "author": pr_author,
+                        "created": pr["created_at"],
+                        "url": pr["html_url"]
+                    })
+                    results["summary"]["prs_without_reviewers"] += 1
+                else:
+                    results["repos"][repo]["prs_with_reviewers"].append({
+                        "number": pr_number,
+                        "title": pr_title,
+                        "author": pr_author,
+                        "has_requested": has_requested,
+                        "has_reviews": has_reviews,
+                        "is_self_review": is_self_review
+                    })
+        
+        return results
+    
+    def generate_report(self, results: Dict[str, Any]) -> str:
+        """Generate a report of reviewer assignment status."""
+        report = "# PR Reviewer Assignment Report\n\n"
+        report += "## Summary\n"
+        report += f"- **Repositories checked:** {results['summary']['repos_checked']}\n"
+        report += f"- **Total open PRs:** {results['summary']['total_prs']}\n"
+        report += f"- **PRs without reviewers:** {results['summary']['prs_without_reviewers']}\n\n"
+        
+        if results['summary']['prs_without_reviewers'] == 0:
+            report += "✅ **All PRs have assigned reviewers.**\n"
+        else:
+            report += "⚠️ **PRs without assigned reviewers:**\n\n"
+            
+            for repo, data in results["repos"].items():
+                if data["prs_without_reviewers"]:
+                    report += f"### {repo}\n"
+                    for pr in data["prs_without_reviewers"]:
+                        report += f"- **#{pr['number']}**: {pr['title']}\n"
+                        report += f"  - Author: {pr['author']}\n"
+                        report += f"  - Created: {pr['created']}\n"
+                        report += f"  - URL: {pr['url']}\n"
+                    report += "\n"
+        
+        report += "## Repository Details\n\n"
+        for repo, data in results["repos"].items():
+            report += f"### {repo}\n"
+            report += f"- **Total PRs:** {data['total_prs']}\n"
+            report += f"- **PRs without reviewers:** {len(data['prs_without_reviewers'])}\n"
+            report += f"- **PRs with reviewers:** {len(data['prs_with_reviewers'])}\n\n"
+            
+            if data['prs_with_reviewers']:
+                report += "**PRs with reviewers:**\n"
+                for pr in data['prs_with_reviewers']:
+                    status = "✅" if pr['has_requested'] else "⚠️"
+                    if pr['is_self_review']:
+                        status = "⚠️ (self-review)"
+                    report += f"- {status} #{pr['number']}: {pr['title']}\n"
+                report += "\n"
+        
+        return report
+    
+    def assign_reviewer(self, repo: str, pr_number: int, reviewer: str) -> bool:
+        """Assign a reviewer to a PR."""
+        endpoint = f"/repos/{ORG}/{repo}/pulls/{pr_number}/requested_reviewers"
+        data = {"reviewers": [reviewer]}
+        
+        url = f"{GITEA_BASE}{endpoint}"
+        headers = {
+            "Authorization": f"token {self.token}",
+            "Content-Type": "application/json"
+        }
+        
+        req = urllib.request.Request(url, headers=headers, method="POST")
+        req.data = json.dumps(data).encode()
+        
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return resp.status == 201
+        except urllib.error.HTTPError as e:
+            print(f"Failed to assign reviewer: {e.code}")
+            return False
+
+
+def main():
+    """Main entry point for reviewer checker."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Check for PRs without assigned reviewers")
+    parser.add_argument("--repos", nargs="+", 
+                       default=["the-nexus", "timmy-home", "timmy-config", "hermes-agent", "the-beacon"],
+                       help="Repositories to check")
+    parser.add_argument("--report", action="store_true", help="Generate report")
+    parser.add_argument("--json", action="store_true", help="Output JSON instead of report")
+    parser.add_argument("--assign", nargs=2, metavar=("REPO", "PR"),
+                       help="Assign a reviewer to a specific PR")
+    parser.add_argument("--reviewer", help="Reviewer to assign (e.g., @perplexity)")
+    
+    args = parser.parse_args()
+    
+    checker = ReviewerChecker()
+    
+    if args.assign:
+        # Assign reviewer to specific PR
+        repo, pr_number = args.assign
+        reviewer = args.reviewer or "@perplexity"
+        
+        if checker.assign_reviewer(repo, int(pr_number), reviewer):
+            print(f"✅ Assigned {reviewer} as reviewer to {repo} #{pr_number}")
+        else:
+            print(f"❌ Failed to assign reviewer to {repo} #{pr_number}")
+            sys.exit(1)
+    else:
+        # Check for PRs without reviewers
+        results = checker.check_prs_without_reviewers(args.repos)
+        
+        if args.json:
+            print(json.dumps(results, indent=2))
+        elif args.report:
+            report = checker.generate_report(results)
+            print(report)
+        else:
+            # Default: show summary
+            print(f"Checked {results['summary']['repos_checked']} repositories")
+            print(f"Total open PRs: {results['summary']['total_prs']}")
+            print(f"PRs without reviewers: {results['summary']['prs_without_reviewers']}")
+            
+            if results['summary']['prs_without_reviewers'] > 0:
+                print("\nPRs without reviewers:")
+                for repo, data in results["repos"].items():
+                    if data["prs_without_reviewers"]:
+                        for pr in data["prs_without_reviewers"]:
+                            print(f"  {repo} #{pr['number']}: {pr['title']}")
+                sys.exit(1)
+            else:
+                print("\n✅ All PRs have assigned reviewers")
+                sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

docs/auto-reviewer-assignment.md

@@ -0,0 +1,227 @@
+# Automated Reviewer Assignment
+
+**Issue:** #1444 - policy: Implement automated reviewer assignment (from Issue #1127 triage)  
+**Purpose:** Ensure all PRs have at least one reviewer assigned
+
+## Problem
+
+From issue #1127 triage:
+> "0 of 14 PRs had a reviewer assigned before this pass."
+
+This means:
+- PRs can be created without any reviewer
+- No automated enforcement of reviewer assignment
+- PRs may sit without review for extended periods
+
+## Solution
+
+### 1. GitHub Actions Workflow (`.gitea/workflows/auto-assign-reviewers.yml`)
+Automatically assigns reviewers when PRs are created:
+
+**When it runs:**
+- On PR open
+- On PR reopen
+- On PR ready for review (not draft)
+
+**What it does:**
+1. Determines appropriate reviewers based on repository
+2. Assigns reviewers via Gitea API
+3. Adds comment about reviewer assignment
+4. Verifies at least one reviewer is assigned
+
+### 2. Reviewer Check Script (`bin/check_reviewers.py`)
+Script to check for PRs without reviewers:
+
+**Usage:**
+```bash
+# Check all repositories
+python bin/check_reviewers.py
+
+# Check specific repositories
+python bin/check_reviewers.py --repos the-nexus timmy-home
+
+# Generate report
+python bin/check_reviewers.py --report
+
+# Assign reviewer to specific PR
+python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity
+```
+
+### 3. CODEOWNERS File (`.github/CODEOWNERS`)
+Defines default reviewers for different paths:
+
+```
+# Default reviewer for all repositories
+* @perplexity
+
+# Specialized component owners
+hermes-agent/ @Timmy
+hermes-agent/agent-core/ @Rockachopa
+hermes-agent/protocol/ @Timmy
+the-nexus/ @perplexity
+the-nexus/ai/ @Timmy
+timmy-home/ @perplexity
+timmy-config/ @perplexity
+
+# Owner gates for critical systems
+hermes-agent/ @Timmy
+```
+
+## Reviewer Assignment Rules
+
+### Repository-Specific Rules
+
+| Repository | Default Reviewers | Required Reviewers | Notes |
+|------------|-------------------|-------------------|-------|
+| hermes-agent | @Timmy, @perplexity | @Timmy | Owner gate for critical system |
+| the-nexus | @perplexity | None | QA gate |
+| timmy-home | @perplexity | None | QA gate |
+| timmy-config | @perplexity | None | QA gate |
+| the-beacon | @perplexity | None | QA gate |
+
+### Special Rules
+
+1. **No self-review:** PR author cannot be assigned as reviewer
+2. **Fallback:** If no reviewers available, assign @perplexity
+3. **Critical systems:** hermes-agent requires @Timmy as reviewer
+
+## How It Works
+
+### Automated Assignment Flow
+
+1. **PR Created** → GitHub Actions workflow triggers
+2. **Determine Reviewers** → Based on repository and CODEOWNERS
+3. **Assign Reviewers** → Via Gitea API
+4. **Add Comment** → Notify about assignment
+5. **Verify** → Ensure at least one reviewer assigned
+
+### Manual Assignment
+
+```bash
+# Assign specific reviewer
+python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity
+
+# Check for PRs without reviewers
+python bin/check_reviewers.py --report
+```
+
+## Configuration
+
+### Environment Variables
+
+- `GITEA_TOKEN`: Gitea API token for authentication
+- `REPO`: Repository name (auto-set in GitHub Actions)
+- `PR_NUMBER`: PR number (auto-set in GitHub Actions)
+
+### Repository Configuration
+
+Edit the workflow to customize reviewer assignment:
+
+```yaml
+# Define default reviewers based on repository
+case "$REPO_NAME" in
+  "hermes-agent")
+    DEFAULT_REVIEWERS=("Timmy" "perplexity")
+    REQUIRED_REVIEWERS=("Timmy")
+    ;;
+  "the-nexus")
+    DEFAULT_REVIEWERS=("perplexity")
+    REQUIRED_REVIEWERS=()
+    ;;
+  # Add more repositories as needed
+esac
+```
+
+## Testing
+
+### Test the workflow:
+
+1. Create a test PR
+2. Check if reviewers are automatically assigned
+3. Verify comment is added
+
+### Test the script:
+
+```bash
+# Check for PRs without reviewers
+python bin/check_reviewers.py --report
+
+# Assign reviewer to test PR
+python bin/check_reviewers.py --assign the-nexus 123 --reviewer @perplexity
+```
+
+## Monitoring
+
+### Check for PRs without reviewers:
+
+```bash
+# Daily check
+python bin/check_reviewers.py --report
+
+# JSON output for automation
+python bin/check_reviewers.py --json
+```
+
+### Review assignment logs:
+
+1. Check GitHub Actions logs for assignment details
+2. Review PR comments for assignment notifications
+3. Monitor for PRs with 0 reviewers
+
+## Enforcement
+
+### CI Check (Future Enhancement)
+
+Add CI check to reject PRs with 0 reviewers:
+
+```yaml
+# In CI workflow
+- name: Check for reviewers
+  run: |
+    REVIEWERS=$(curl -s "https://forge.alexanderwhitestone.com/api/v1/repos/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
+      -H "Authorization: token $GITEA_TOKEN" | jq '.users | length')
+    
+    if [ "$REVIEWERS" -eq 0 ]; then
+      echo "❌ ERROR: PR has no reviewers assigned"
+      exit 1
+    fi
+```
+
+### Policy Enforcement
+
+1. **All PRs must have reviewers** - No exceptions
+2. **No self-review** - PR author cannot review own PR
+3. **Critical systems require specific reviewers** - hermes-agent requires @Timmy
+
+## Related Issues
+
+- **Issue #1127:** Perplexity Evening Pass triage (identified missing reviewers)
+- **Issue #1444:** This implementation
+- **Issue #1336:** Merge conflicts in CODEOWNERS (fixed)
+
+## Files Added/Modified
+
+1. `.gitea/workflows/auto-assign-reviewers.yml` - GitHub Actions workflow
+2. `bin/check_reviewers.py` - Reviewer check script
+3. `.github/CODEOWNERS` - Cleaned up CODEOWNERS file
+4. `docs/auto-reviewer-assignment.md` - This documentation
+
+## Future Enhancements
+
+1. **CI check for 0 reviewers** - Reject PRs without reviewers
+2. **Slack/Telegram notifications** - Notify when PRs lack reviewers
+3. **Load balancing** - Distribute reviews evenly among team members
+4. **Auto-assign based on file changes** - Assign specialists for specific areas
+
+## Conclusion
+
+This implementation ensures all PRs have at least one reviewer assigned:
+- **Automated assignment** on PR creation
+- **Manual checking** for existing PRs
+- **Clear documentation** of policies and procedures
+
+**Result:** No more PRs sitting without reviewers.
+
+## License
+
+Part of the Timmy Foundation project.

server.py

@@ -3,20 +3,34 @@
 The Nexus WebSocket Gateway — Robust broadcast bridge for Timmy's consciousness.
 This server acts as the central hub for the-nexus, connecting the mind (nexus_think.py),
 the body (Evennia/Morrowind), and the visualization surface.
+
+Security features:
+- Binds to 127.0.0.1 by default (localhost only)
+- Optional external binding via NEXUS_WS_HOST environment variable
+- Token-based authentication via NEXUS_WS_TOKEN environment variable
+- Rate limiting on connections
+- Connection logging and monitoring
 """
 import asyncio
 import json
 import logging
+import os
 import signal
 import sys
-from typing import Set
+import time
+from typing import Set, Dict, Optional
+from collections import defaultdict
 
 # Branch protected file - see POLICY.md
 import websockets
 
 # Configuration
-PORT = 8765
+PORT = int(os.environ.get("NEXUS_WS_PORT", "8765"))
-HOST = "0.0.0.0"  # Allow external connections if needed
+HOST = os.environ.get("NEXUS_WS_HOST", "127.0.0.1")  # Default to localhost only
+AUTH_TOKEN = os.environ.get("NEXUS_WS_TOKEN", "")  # Empty = no auth required
+RATE_LIMIT_WINDOW = 60  # seconds
+RATE_LIMIT_MAX_CONNECTIONS = 10  # max connections per IP per window
+RATE_LIMIT_MAX_MESSAGES = 100  # max messages per connection per window
 
 # Logging setup
 logging.basicConfig(
@@ -28,15 +42,97 @@ logger = logging.getLogger("nexus-gateway")
 
 # State
 clients: Set[websockets.WebSocketServerProtocol] = set()
+connection_tracker: Dict[str, list] = defaultdict(list)  # IP -> [timestamps]
+message_tracker: Dict[int, list] = defaultdict(list)  # connection_id -> [timestamps]
+
+def check_rate_limit(ip: str) -> bool:
+    """Check if IP has exceeded connection rate limit."""
+    now = time.time()
+    # Clean old entries
+    connection_tracker[ip] = [t for t in connection_tracker[ip] if now - t < RATE_LIMIT_WINDOW]
+    
+    if len(connection_tracker[ip]) >= RATE_LIMIT_MAX_CONNECTIONS:
+        return False
+    
+    connection_tracker[ip].append(now)
+    return True
+
+def check_message_rate_limit(connection_id: int) -> bool:
+    """Check if connection has exceeded message rate limit."""
+    now = time.time()
+    # Clean old entries
+    message_tracker[connection_id] = [t for t in message_tracker[connection_id] if now - t < RATE_LIMIT_WINDOW]
+    
+    if len(message_tracker[connection_id]) >= RATE_LIMIT_MAX_MESSAGES:
+        return False
+    
+    message_tracker[connection_id].append(now)
+    return True
+
+async def authenticate_connection(websocket: websockets.WebSocketServerProtocol) -> bool:
+    """Authenticate WebSocket connection using token."""
+    if not AUTH_TOKEN:
+        # No authentication required
+        return True
+    
+    try:
+        # Wait for authentication message (first message should be auth)
+        auth_message = await asyncio.wait_for(websocket.recv(), timeout=5.0)
+        auth_data = json.loads(auth_message)
+        
+        if auth_data.get("type") != "auth":
+            logger.warning(f"Invalid auth message type from {websocket.remote_address}")
+            return False
+        
+        token = auth_data.get("token", "")
+        if token != AUTH_TOKEN:
+            logger.warning(f"Invalid auth token from {websocket.remote_address}")
+            return False
+        
+        logger.info(f"Authenticated connection from {websocket.remote_address}")
+        return True
+        
+    except asyncio.TimeoutError:
+        logger.warning(f"Authentication timeout from {websocket.remote_address}")
+        return False
+    except json.JSONDecodeError:
+        logger.warning(f"Invalid auth JSON from {websocket.remote_address}")
+        return False
+    except Exception as e:
+        logger.error(f"Authentication error from {websocket.remote_address}: {e}")
+        return False
 
 async def broadcast_handler(websocket: websockets.WebSocketServerProtocol):
     """Handles individual client connections and message broadcasting."""
-    clients.add(websocket)
     addr = websocket.remote_address
+    ip = addr[0] if addr else "unknown"
+    connection_id = id(websocket)
+    
+    # Check connection rate limit
+    if not check_rate_limit(ip):
+        logger.warning(f"Connection rate limit exceeded for {ip}")
+        await websocket.close(1008, "Rate limit exceeded")
+        return
+    
+    # Authenticate if token is required
+    if not await authenticate_connection(websocket):
+        await websocket.close(1008, "Authentication failed")
+        return
+    
+    clients.add(websocket)
     logger.info(f"Client connected from {addr}. Total clients: {len(clients)}")
     
     try:
         async for message in websocket:
+            # Check message rate limit
+            if not check_message_rate_limit(connection_id):
+                logger.warning(f"Message rate limit exceeded for {addr}")
+                await websocket.send(json.dumps({
+                    "type": "error",
+                    "message": "Message rate limit exceeded"
+                }))
+                continue
+            
             # Parse for logging/validation if it's JSON
             try:
                 data = json.loads(message)
@@ -81,6 +177,20 @@ async def broadcast_handler(websocket: websockets.WebSocketServerProtocol):
 
 async def main():
     """Main server loop with graceful shutdown."""
+    # Log security configuration
+    if AUTH_TOKEN:
+        logger.info("Authentication: ENABLED (token required)")
+    else:
+        logger.warning("Authentication: DISABLED (no token required)")
+    
+    if HOST == "0.0.0.0":
+        logger.warning("Host binding: 0.0.0.0 (all interfaces) - SECURITY RISK")
+    else:
+        logger.info(f"Host binding: {HOST} (localhost only)")
+    
+    logger.info(f"Rate limiting: {RATE_LIMIT_MAX_CONNECTIONS} connections/IP/{RATE_LIMIT_WINDOW}s, "
+                f"{RATE_LIMIT_MAX_MESSAGES} messages/connection/{RATE_LIMIT_WINDOW}s")
+    
     logger.info(f"Starting Nexus WS gateway on ws://{HOST}:{PORT}")
     
     # Set up signal handlers for graceful shutdown

tests/load/websocket_load_test.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+WebSocket Load Test — Benchmark concurrent user sessions on the Nexus gateway.
+
+Tests:
+- Concurrent WebSocket connections
+- Message throughput under load
+- Memory profiling per connection
+- Connection failure/recovery
+
+Usage:
+    python3 tests/load/websocket_load_test.py                    # default (50 users)
+    python3 tests/load/websocket_load_test.py --users 200        # 200 concurrent
+    python3 tests/load/websocket_load_test.py --duration 60      # 60 second test
+    python3 tests/load/websocket_load_test.py --json             # JSON output
+
+Ref: #1505
+"""
+
+import asyncio
+import json
+import os
+import sys
+import time
+import argparse
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+WS_URL = os.environ.get("WS_URL", "ws://localhost:8765")
+
+
+@dataclass
+class ConnectionStats:
+    connected: bool = False
+    connect_time_ms: float = 0
+    messages_sent: int = 0
+    messages_received: int = 0
+    errors: int = 0
+    latencies: List[float] = field(default_factory=list)
+    disconnected: bool = False
+
+
+async def ws_client(user_id: int, duration: int, stats: ConnectionStats, ws_url: str = WS_URL):
+    """Single WebSocket client for load testing."""
+    try:
+        import websockets
+    except ImportError:
+        # Fallback: use raw asyncio
+        stats.errors += 1
+        return
+
+    try:
+        start = time.time()
+        async with websockets.connect(ws_url, open_timeout=5) as ws:
+            stats.connect_time_ms = (time.time() - start) * 1000
+            stats.connected = True
+
+            # Send periodic messages for the duration
+            end_time = time.time() + duration
+            msg_count = 0
+            while time.time() < end_time:
+                try:
+                    msg_start = time.time()
+                    message = json.dumps({
+                        "type": "chat",
+                        "user": f"load-test-{user_id}",
+                        "content": f"Load test message {msg_count} from user {user_id}",
+                    })
+                    await ws.send(message)
+                    stats.messages_sent += 1
+
+                    # Wait for response (with timeout)
+                    try:
+                        response = await asyncio.wait_for(ws.recv(), timeout=5.0)
+                        stats.messages_received += 1
+                        latency = (time.time() - msg_start) * 1000
+                        stats.latencies.append(latency)
+                    except asyncio.TimeoutError:
+                        stats.errors += 1
+
+                    msg_count += 1
+                    await asyncio.sleep(0.5)  # 2 messages/sec per user
+
+                except websockets.exceptions.ConnectionClosed:
+                    stats.disconnected = True
+                    break
+                except Exception:
+                    stats.errors += 1
+
+    except Exception as e:
+        stats.errors += 1
+        if "Connection refused" in str(e) or "connect" in str(e).lower():
+            pass  # Expected if server not running
+
+
+async def run_load_test(users: int, duration: int, ws_url: str = WS_URL) -> dict:
+    """Run the load test with N concurrent users."""
+    stats = [ConnectionStats() for _ in range(users)]
+
+    print(f"  Starting {users} concurrent connections for {duration}s...")
+    start = time.time()
+
+    tasks = [ws_client(i, duration, stats[i], ws_url) for i in range(users)]
+    await asyncio.gather(*tasks, return_exceptions=True)
+
+    total_time = time.time() - start
+
+    # Aggregate results
+    connected = sum(1 for s in stats if s.connected)
+    total_sent = sum(s.messages_sent for s in stats)
+    total_received = sum(s.messages_received for s in stats)
+    total_errors = sum(s.errors for s in stats)
+    disconnected = sum(1 for s in stats if s.disconnected)
+
+    all_latencies = []
+    for s in stats:
+        all_latencies.extend(s.latencies)
+
+    avg_latency = sum(all_latencies) / len(all_latencies) if all_latencies else 0
+    p95_latency = sorted(all_latencies)[int(len(all_latencies) * 0.95)] if all_latencies else 0
+    p99_latency = sorted(all_latencies)[int(len(all_latencies) * 0.99)] if all_latencies else 0
+
+    avg_connect_time = sum(s.connect_time_ms for s in stats if s.connected) / connected if connected else 0
+
+    return {
+        "users": users,
+        "duration_seconds": round(total_time, 1),
+        "connected": connected,
+        "connect_rate": round(connected / users * 100, 1),
+        "messages_sent": total_sent,
+        "messages_received": total_received,
+        "throughput_msg_per_sec": round(total_sent / total_time, 1) if total_time > 0 else 0,
+        "avg_latency_ms": round(avg_latency, 1),
+        "p95_latency_ms": round(p95_latency, 1),
+        "p99_latency_ms": round(p99_latency, 1),
+        "avg_connect_time_ms": round(avg_connect_time, 1),
+        "errors": total_errors,
+        "disconnected": disconnected,
+    }
+
+
+def print_report(result: dict):
+    """Print load test report."""
+    print(f"\n{'='*60}")
+    print(f"  WEBSOCKET LOAD TEST REPORT")
+    print(f"{'='*60}\n")
+
+    print(f"  Connections:    {result['connected']}/{result['users']} ({result['connect_rate']}%)")
+    print(f"  Duration:       {result['duration_seconds']}s")
+    print(f"  Messages sent:  {result['messages_sent']}")
+    print(f"  Messages recv:  {result['messages_received']}")
+    print(f"  Throughput:     {result['throughput_msg_per_sec']} msg/s")
+    print(f"  Avg connect:    {result['avg_connect_time_ms']}ms")
+    print()
+    print(f"  Latency:")
+    print(f"    Avg: {result['avg_latency_ms']}ms")
+    print(f"    P95: {result['p95_latency_ms']}ms")
+    print(f"    P99: {result['p99_latency_ms']}ms")
+    print()
+    print(f"  Errors:         {result['errors']}")
+    print(f"  Disconnected:   {result['disconnected']}")
+
+    # Verdict
+    if result['connect_rate'] >= 95 and result['errors'] == 0:
+        print(f"\n  ✅ PASS")
+    elif result['connect_rate'] >= 80:
+        print(f"\n  ⚠️  DEGRADED")
+    else:
+        print(f"\n  ❌ FAIL")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="WebSocket Load Test")
+    parser.add_argument("--users", type=int, default=50, help="Concurrent users")
+    parser.add_argument("--duration", type=int, default=30, help="Test duration in seconds")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    parser.add_argument("--url", default=WS_URL, help="WebSocket URL")
+    args = parser.parse_args()
+
+    ws_url = args.url
+
+    print(f"\nWebSocket Load Test — {args.users} users, {args.duration}s\n")
+
+    result = asyncio.run(run_load_test(args.users, args.duration, ws_url))
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print_report(result)
+
+
+if __name__ == "__main__":
+    main()