Jason Woltje
e23c09f1f2
Implement FastAPI webhook receiver for Gitea issue assignment events with HMAC SHA256 signature verification and event routing. Implementation details: - FastAPI application with /webhook/gitea POST endpoint - HMAC SHA256 signature verification in security.py - Event routing for assigned, unassigned, closed actions - Comprehensive logging for all webhook events - Health check endpoint at /health - Docker containerization with health checks - 91% test coverage (exceeds 85% requirement) TDD workflow followed: - Wrote 16 tests first (RED phase) - Implemented features to pass tests (GREEN phase) - All tests passing with 91% coverage - Type checking with mypy: success - Linting with ruff: success Files created: - apps/coordinator/src/main.py - FastAPI application - apps/coordinator/src/webhook.py - Webhook handlers - apps/coordinator/src/security.py - HMAC verification - apps/coordinator/src/config.py - Configuration management - apps/coordinator/tests/ - Comprehensive test suite - apps/coordinator/Dockerfile - Production container - apps/coordinator/pyproject.toml - Python project config Configuration: - Updated .env.example with GITEA_WEBHOOK_SECRET - Updated docker-compose.yml with coordinator service Testing: - 16 unit and integration tests - Security tests for signature verification - Event handler tests for all supported actions - Health check endpoint tests - All tests passing with 91% coverage This unblocks issue #158 (issue parser). Fixes #157 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
142 lines
3.1 KiB
Markdown
142 lines
3.1 KiB
Markdown
# Mosaic Coordinator
|
|
|
|
FastAPI webhook receiver for Gitea issue events, enabling autonomous task coordination for AI agents.
|
|
|
|
## Overview
|
|
|
|
The coordinator receives webhook events from Gitea when issues are assigned, unassigned, or closed. It verifies webhook authenticity via HMAC SHA256 signature and routes events to appropriate handlers.
|
|
|
|
## Features
|
|
|
|
- HMAC SHA256 signature verification
|
|
- Event routing (assigned, unassigned, closed)
|
|
- Comprehensive logging
|
|
- Health check endpoint
|
|
- Docker containerized
|
|
- 85%+ test coverage
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.11+
|
|
- pip or uv package manager
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run with coverage
|
|
pytest --cov=src --cov-report=html
|
|
|
|
# Type checking
|
|
mypy src/
|
|
|
|
# Linting
|
|
ruff check src/
|
|
```
|
|
|
|
### Running locally
|
|
|
|
```bash
|
|
# Set environment variables
|
|
export GITEA_WEBHOOK_SECRET="your-secret-here"
|
|
export LOG_LEVEL="info"
|
|
|
|
# Run server
|
|
uvicorn src.main:app --reload --port 8000
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### POST /webhook/gitea
|
|
|
|
Receives Gitea webhook events.
|
|
|
|
**Headers:**
|
|
|
|
- `X-Gitea-Signature`: HMAC SHA256 signature of request body
|
|
|
|
**Response:**
|
|
|
|
- `200 OK`: Event processed successfully
|
|
- `401 Unauthorized`: Invalid or missing signature
|
|
- `422 Unprocessable Entity`: Invalid payload
|
|
|
|
### GET /health
|
|
|
|
Health check endpoint.
|
|
|
|
**Response:**
|
|
|
|
- `200 OK`: Service is healthy
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Required | Default |
|
|
| ---------------------- | ------------------------------------------- | -------- | ------- |
|
|
| `GITEA_WEBHOOK_SECRET` | Secret for HMAC signature verification | Yes | - |
|
|
| `GITEA_URL` | Gitea instance URL | Yes | - |
|
|
| `LOG_LEVEL` | Logging level (debug, info, warning, error) | No | info |
|
|
| `HOST` | Server host | No | 0.0.0.0 |
|
|
| `PORT` | Server port | No | 8000 |
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
# Build
|
|
docker build -t mosaic-coordinator .
|
|
|
|
# Run
|
|
docker run -p 8000:8000 \
|
|
-e GITEA_WEBHOOK_SECRET="your-secret" \
|
|
-e GITEA_URL="https://git.mosaicstack.dev" \
|
|
mosaic-coordinator
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
pytest
|
|
|
|
# Run with coverage (requires 85%+)
|
|
pytest --cov=src --cov-report=term-missing
|
|
|
|
# Run specific test file
|
|
pytest tests/test_security.py
|
|
|
|
# Run with verbose output
|
|
pytest -v
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
apps/coordinator/
|
|
├── src/
|
|
│ ├── main.py # FastAPI application
|
|
│ ├── webhook.py # Webhook endpoint handlers
|
|
│ ├── security.py # HMAC signature verification
|
|
│ └── config.py # Configuration management
|
|
├── tests/
|
|
│ ├── test_security.py
|
|
│ ├── test_webhook.py
|
|
│ └── conftest.py # Pytest fixtures
|
|
├── pyproject.toml # Project metadata & dependencies
|
|
├── Dockerfile
|
|
└── README.md
|
|
```
|
|
|
|
## Related Issues
|
|
|
|
- #156 - Create coordinator bot user
|
|
- #157 - Set up webhook receiver endpoint
|
|
- #158 - Implement issue parser
|
|
- #140 - Coordinator architecture
|