Add user submission management API endpoints (#412)

Mark Saroufim · web-flow · commit bb4bea065127 · 2026-02-06T08:06:55.000-08:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -16,12 +16,167 @@ uv run ruff check . --exclude examples/ --line-length 120
 
 ## Testing
 
+### Unit Tests
+
 Run tests with pytest:
 
 ```bash
 uv run pytest tests/ -v
 ```
 
+### Test Requirements
+
+When adding new functionality:
+
+1. **Database methods** (`src/libkernelbot/leaderboard_db.py`):
+   - Add tests to `tests/test_leaderboard_db.py`
+   - Test empty results, basic functionality, edge cases, and pagination
+
+2. **API endpoints** (`src/kernelbot/api/main.py`):
+   - Add tests to `tests/test_admin_api.py` or create endpoint-specific test files
+   - Test authentication, authorization (403), not found (404), and validation (400)
+
+3. **Regression tests**: Use the popcorn-cli against a local instance to verify end-to-end functionality
+
+### E2E Regression Testing with popcorn-cli
+
+Full end-to-end testing requires running the API server locally and testing with popcorn-cli. This tests the complete flow from CLI through API to database.
+
+#### Step 1: Start PostgreSQL
+
+```bash
+# macOS with Homebrew
+brew services start postgresql@14
+
+# Verify it's running
+pg_isready
+```
+
+#### Step 2: Create Database and Run Migrations
+
+```bash
+# Create database (first time only)
+createdb kernelbot
+
+# Run migrations
+export DATABASE_URL="postgresql://$(whoami)@localhost:5432/kernelbot"
+uv run yoyo apply --database "$DATABASE_URL" src/migrations/
+```
+
+#### Step 3: Create a Test User
+
+The CLI requires a registered user. Create one in the database:
+
+```bash
+export DATABASE_URL="postgresql://$(whoami)@localhost:5432/kernelbot"
+psql "$DATABASE_URL" -c "INSERT INTO leaderboard.user_info (id, user_name, cli_id, cli_valid)
+VALUES ('999999', 'testuser', 'test-cli-id-123', true)
+ON CONFLICT (id) DO UPDATE SET cli_id = 'test-cli-id-123', cli_valid = true;"
+```
+
+#### Step 4: Start the API Server
+
+```bash
+cd src/kernelbot
+
+# Set required environment variables
+export DATABASE_URL="postgresql://$(whoami)@localhost:5432/kernelbot"
+export ADMIN_TOKEN="your-admin-token-here"  # Check .env for LOCAL_ADMIN_TOKEN
+
+# Start API server (without Discord bot)
+uv run python main.py --api-only
+
+# Server runs on http://localhost:8000
+```
+
+#### Step 5: Sync Leaderboards
+
+Leaderboards must be synced from reference-kernels before testing submissions:
+
+```bash
+curl -X POST "http://localhost:8000/admin/update-problems" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"problem_set": "pmpp_v2"}'
+```
+
+#### Step 6: Configure popcorn-cli for Local Testing
+
+Temporarily update `~/.popcorn.yaml` to use test credentials:
+
+```bash
+# Backup existing config
+cp ~/.popcorn.yaml ~/.popcorn.yaml.bak
+
+# Set test CLI ID
+echo "cli_id: test-cli-id-123" > ~/.popcorn.yaml
+```
+
+#### Step 7: Run CLI Commands
+
+```bash
+cd /path/to/popcorn-cli
+
+# Set API URL to local server
+export POPCORN_API_URL=http://localhost:8000
+
+# Test various commands
+cargo run --release -- submissions list --leaderboard vectoradd_v2
+cargo run --release -- submissions show <ID>
+cargo run --release -- submissions delete <ID>
+
+# Test submission (runs on Modal H100, requires Modal account)
+cargo run --release -- submit solution.py --gpu H100 --leaderboard vectoradd_v2 --mode test
+```
+
+#### Step 8: Restore Original Config
+
+```bash
+cp ~/.popcorn.yaml.bak ~/.popcorn.yaml
+rm ~/.popcorn.yaml.bak
+```
+
+#### Quick Reference: Testing API Endpoints Directly
+
+```bash
+# List user submissions
+curl -s "http://localhost:8000/user/submissions?leaderboard=vectoradd_v2" \
+  -H "X-Popcorn-Cli-Id: test-cli-id-123"
+
+# Get submission details
+curl -s "http://localhost:8000/user/submissions/1" \
+  -H "X-Popcorn-Cli-Id: test-cli-id-123"
+
+# Delete submission
+curl -s -X DELETE "http://localhost:8000/user/submissions/1" \
+  -H "X-Popcorn-Cli-Id: test-cli-id-123"
+
+# Submit a file (multipart form)
+curl -s -X POST "http://localhost:8000/vectoradd_v2/H100/test" \
+  -H "X-Popcorn-Cli-Id: test-cli-id-123" \
+  -F "file=@solution.py"
+```
+
+#### Troubleshooting
+
+- **401 Unauthorized**: CLI ID not in database or `cli_valid` is false
+- **404 Not Found**: Leaderboards not synced - run update-problems first
+- **500 Internal Error**: Check server logs in terminal, often a TypedDict vs object access issue
+- **"Device not configured" from CLI**: Usually a TTY issue, try running with explicit env vars
+
+## Before Adding New Features
+
+**Important:** Check for existing code before implementing:
+
+1. **Database methods**: `src/libkernelbot/leaderboard_db.py`
+2. **Discord commands**: `src/kernelbot/cogs/`
+3. **API endpoints**: `src/kernelbot/api/main.py`
+
+Reuse existing patterns:
+- `validate_user_header` / `validate_cli_header` for authentication
+- `get_submission_by_id()`, `delete_submission()` for submission operations
+- `simple_rate_limit()` for rate limiting
+
 ## Local Development
 
 See `SKILLS/test_bot.md` for local testing setup instructions.
diff --git a/src/kernelbot/api/main.py b/src/kernelbot/api/main.py
@@ -711,3 +711,121 @@ async def get_submission_count(
             return {"count": count}
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Error fetching submission count: {e}") from e
+
+
+@app.get("/user/submissions")
+async def get_user_submissions(
+    user_info: Annotated[dict, Depends(validate_user_header)],
+    leaderboard: Optional[str] = None,
+    limit: int = 50,
+    offset: int = 0,
+    db_context=Depends(get_db),
+) -> list[dict]:
+    """Get the authenticated user's submissions.
+
+    Args:
+        leaderboard: Optional filter by leaderboard name
+        limit: Maximum number of submissions to return (default 50, max 100)
+        offset: Offset for pagination (must be >= 0)
+
+    Returns:
+        List of user's submissions with summary info
+    """
+    await simple_rate_limit()
+
+    # Validate inputs (DB also validates, but fail fast here)
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=400, detail="limit must be between 1 and 100")
+    if offset < 0:
+        raise HTTPException(status_code=400, detail="offset must be >= 0")
+
+    try:
+        with db_context as db:
+            return db.get_user_submissions(
+                user_id=user_info["user_id"],
+                leaderboard_name=leaderboard,
+                limit=limit,
+                offset=offset,
+            )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error fetching user submissions: {e}") from e
+
+
+@app.get("/user/submissions/{submission_id}")
+async def get_user_submission(
+    submission_id: int,
+    user_info: Annotated[dict, Depends(validate_user_header)],
+    db_context=Depends(get_db),
+) -> dict:
+    """Get a specific submission by ID. Only the owner can view their submission.
+
+    Args:
+        submission_id: The submission ID to retrieve
+
+    Returns:
+        Full submission details including code
+    """
+    await simple_rate_limit()
+    try:
+        with db_context as db:
+            submission = db.get_submission_by_id(submission_id)
+
+            if submission is None:
+                raise HTTPException(status_code=404, detail="Submission not found")
+
+            # Verify ownership
+            if str(submission["user_id"]) != str(user_info["user_id"]):
+                raise HTTPException(status_code=403, detail="Not authorized to view this submission")
+
+            # RunItem is a TypedDict (already a dict), select fields to expose
+            run_fields = ("start_time", "end_time", "mode", "secret", "runner", "score", "passed")
+            return {
+                "id": submission["submission_id"],
+                "leaderboard_id": submission["leaderboard_id"],
+                "leaderboard_name": submission["leaderboard_name"],
+                "file_name": submission["file_name"],
+                "user_id": submission["user_id"],
+                "submission_time": submission["submission_time"],
+                "done": submission["done"],
+                "code": submission["code"],
+                "runs": [{k: r[k] for k in run_fields} for r in submission["runs"]],
+            }
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error fetching submission: {e}") from e
+
+
+@app.delete("/user/submissions/{submission_id}")
+async def delete_user_submission(
+    submission_id: int,
+    user_info: Annotated[dict, Depends(validate_user_header)],
+    db_context=Depends(get_db),
+) -> dict:
+    """Delete a submission by ID. Only the owner can delete their submission.
+
+    Args:
+        submission_id: The submission ID to delete
+
+    Returns:
+        Success message
+    """
+    await simple_rate_limit()
+    try:
+        with db_context as db:
+            submission = db.get_submission_by_id(submission_id)
+
+            if submission is None:
+                raise HTTPException(status_code=404, detail="Submission not found")
+
+            # Verify ownership
+            if str(submission["user_id"]) != str(user_info["user_id"]):
+                raise HTTPException(status_code=403, detail="Not authorized to delete this submission")
+
+            db.delete_submission(submission_id)
+
+            return {"status": "ok", "submission_id": submission_id}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error deleting submission: {e}") from e
diff --git a/src/libkernelbot/leaderboard_db.py b/src/libkernelbot/leaderboard_db.py
@@ -848,6 +848,90 @@ def delete_submission(self, submission_id: int):
             logger.exception("Could not delete submission %s.", submission_id, exc_info=e)
             raise KernelBotError(f"Could not delete submission {submission_id}!") from e
 
+    def get_user_submissions(
+        self,
+        user_id: str,
+        leaderboard_name: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[dict]:
+        """
+        Get submissions for a specific user.
+
+        Args:
+            user_id: The user's ID
+            leaderboard_name: Optional filter by leaderboard name
+            limit: Maximum number of submissions to return (max 100)
+            offset: Offset for pagination
+
+        Returns:
+            List of submission dictionaries with summary info and runs
+        """
+        # Validate and clamp inputs
+        limit = max(1, min(limit, 100))
+        offset = max(0, offset)
+
+        try:
+            # Build query with conditional WHERE clause
+            where_clause = "WHERE s.user_id = %s"
+            params: list = [user_id]
+
+            if leaderboard_name:
+                where_clause += " AND lb.name = %s"
+                params.append(leaderboard_name)
+
+            # First, get distinct submissions
+            submission_query = f"""
+                SELECT s.id, lb.name as leaderboard_name, s.file_name,
+                       s.submission_time, s.done
+                FROM leaderboard.submission s
+                JOIN leaderboard.leaderboard lb ON s.leaderboard_id = lb.id
+                {where_clause}
+                ORDER BY s.submission_time DESC
+                LIMIT %s OFFSET %s
+            """
+            self.cursor.execute(submission_query, params + [limit, offset])
+            submissions = self.cursor.fetchall()
+
+            if not submissions:
+                return []
+
+            # Get all runs for these submissions
+            submission_ids = [row[0] for row in submissions]
+            runs_query = """
+                SELECT submission_id, runner as gpu_type, score
+                FROM leaderboard.runs
+                WHERE submission_id = ANY(%s) AND NOT secret AND passed
+            """
+            self.cursor.execute(runs_query, (submission_ids,))
+            runs_by_submission: dict = {}
+            for run_row in self.cursor.fetchall():
+                sub_id = run_row[0]
+                if sub_id not in runs_by_submission:
+                    runs_by_submission[sub_id] = []
+                runs_by_submission[sub_id].append({
+                    "gpu_type": run_row[1],
+                    "score": run_row[2],
+                })
+
+            # Build result with runs grouped by submission
+            results = []
+            for row in submissions:
+                sub_id = row[0]
+                results.append({
+                    "id": sub_id,
+                    "leaderboard_name": row[1],
+                    "file_name": row[2],
+                    "submission_time": row[3],
+                    "done": row[4],
+                    "runs": runs_by_submission.get(sub_id, []),
+                })
+            return results
+        except psycopg2.Error as e:
+            self.connection.rollback()
+            logger.exception("Error fetching user submissions for user %s", user_id, exc_info=e)
+            raise KernelBotError("Error fetching user submissions") from e
+
     def get_submission_by_id(self, submission_id: int) -> Optional["SubmissionItem"]:
         query = """
                 SELECT s.leaderboard_id, lb.name, s.file_name, s.user_id,
diff --git a/src/libkernelbot/problem_sync.py b/src/libkernelbot/problem_sync.py
@@ -75,7 +75,7 @@ def download_problem_repo(repository: str, branch: str, temp_dir: str) -> Path:
     # Download
     try:
         subprocess.check_call(
-            ["wget", "-q", "-O", f"{temp_dir}/problems.zip", url],
+            ["curl", "-sL", "-o", f"{temp_dir}/problems.zip", url],
             encoding="utf-8",
             timeout=60,
         )
diff --git a/tests/test_leaderboard_db.py b/tests/test_leaderboard_db.py

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ def download_problem_repo(repository: str, branch: str, temp_dir: str) -> Path:`
`75`	`75`	`# Download`
`76`	`76`	`try:`
`77`	`77`	`subprocess.check_call(`
`78`		`- ["wget", "-q", "-O", f"{temp_dir}/problems.zip", url],`
	`78`	`+ ["curl", "-sL", "-o", f"{temp_dir}/problems.zip", url],`
`79`	`79`	`encoding="utf-8",`
`80`	`80`	`timeout=60,`
`81`	`81`	`)`