feat(#157): Set up webhook receiver endpoint

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>
This commit is contained in:
2026-02-01 17:41:46 -06:00
parent 658ec0774d
commit e23c09f1f2
17 changed files with 1118 additions and 0 deletions

View File

@@ -0,0 +1,56 @@
# Issue #157: Set up webhook receiver endpoint
## Objective
Implement FastAPI webhook receiver that handles Gitea issue assignment events with HMAC SHA256 signature verification.
## Approach
1. Create new Python service: `apps/coordinator/` (FastAPI app)
2. Structure:
- `src/main.py` - FastAPI application entry point
- `src/webhook.py` - Webhook endpoint handlers
- `src/security.py` - HMAC signature verification
- `src/config.py` - Configuration management
- `tests/` - Unit and integration tests
3. Follow TDD: Write tests first, then implementation
4. Add Docker support with health checks
5. Update docker-compose for coordinator service
## Progress
- [x] Create directory structure
- [x] Write tests for HMAC signature verification (RED)
- [x] Implement signature verification (GREEN)
- [x] Write tests for webhook endpoint (RED)
- [x] Implement webhook endpoint (GREEN)
- [x] Write tests for event routing (RED)
- [x] Implement event routing (GREEN)
- [x] Add health check endpoint
- [x] Create Dockerfile
- [x] Update docker-compose.yml
- [x] Run quality gates (build, lint, test, coverage)
- [x] Update .env.example with webhook secret
- [ ] Commit implementation
- [ ] Update issue status
## Testing
- Unit tests for `security.verify_signature()`
- Unit tests for each event handler (assigned, unassigned, closed)
- Integration test with mock Gitea webhook payload
- Security test: Invalid signature returns 401
- Health check test
## Notes
- Python service alongside NestJS apps (polyglot monorepo)
- Use pytest for testing framework
- Use pydantic for request validation
- Minimum 85% coverage required
- Need to add webhook secret to .env.example
## Token Tracking
- Estimated: 52,000 tokens
- Actual: TBD