72d16929ca
Major refactoring to hexagonal (ports & adapters) architecture: - Add service layer (apikey_service, project_service) for business logic - Add webhook system with dispatcher and delivery tracking - Add command queue with priority-based processing - Add rate limiting with sliding window algorithm - Add audit logging for command execution - Add OpenTelemetry integration (traces, metrics, spans) - Add circuit breaker for fault tolerance - Add cached repository wrapper for performance - Add comprehensive validation package - Add Kubernetes client integration for pod management - Add database migrations (allowed_ips, audit_log, rate_limiting, queue, webhooks) - Add network policy and PodDisruptionBudget for k8s - Remove legacy executor and projects/registry packages - Untrack secrets.yaml (now managed via envault) - Add coverage.out to .gitignore - Add e2e test infrastructure with docker-compose - Add comprehensive documentation (API, architecture, operations, plans) - Add golangci-lint config and pre-commit hook Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
141 lines
7.3 KiB
Markdown
141 lines
7.3 KiB
Markdown
# rdev Architecture
|
|
|
|
rdev is a remote development API that enables secure command execution in isolated Kubernetes pods. This document provides an overview of the system architecture.
|
|
|
|
## System Context
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ rdev API │
|
|
│ │
|
|
┌──────────┐ │ ┌──────────┐ ┌───────────┐ ┌───────────┐ │ ┌──────────┐
|
|
│ Client │────┼─▶│ HTTP │──▶│ Service │──▶│ Adapter │──┼───▶│ K8s │
|
|
│ (SDK) │◀───┼──│ Handler │◀──│ Layer │◀──│ Layer │◀─┼────│ Cluster │
|
|
└──────────┘ │ └──────────┘ └───────────┘ └───────────┘ │ └──────────┘
|
|
│ │ │ │ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌──────────┐ ┌───────────┐ ┌───────────┐ │
|
|
│ │ Auth │ │ Domain │ │ Postgres │ │
|
|
│ │Middleware│ │ Models │ │ DB │ │
|
|
│ └──────────┘ └───────────┘ └───────────┘ │
|
|
└─────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### HTTP Layer
|
|
- **Handlers**: REST endpoints for projects, commands, SSE streaming, API keys
|
|
- **Middleware**: Authentication, rate limiting, metrics, logging
|
|
- **Validation**: Input sanitization, command filtering
|
|
|
|
### Service Layer
|
|
- **ProjectService**: Project lifecycle management
|
|
- **AuthService**: API key management, validation
|
|
|
|
### Adapter Layer
|
|
- **Kubernetes Executor**: Command execution via kubectl exec
|
|
- **Project Repository**: Pod discovery, status monitoring
|
|
- **Postgres Repository**: API key storage
|
|
|
|
### Domain
|
|
- **Models**: Project, Command, APIKey, Scope
|
|
- **Errors**: Domain-specific error types
|
|
- **Events**: Command output, completion events
|
|
|
|
## Architecture Patterns
|
|
|
|
### Hexagonal Architecture (Ports & Adapters)
|
|
|
|
See [hexagonal.md](hexagonal.md) for detailed explanation.
|
|
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ Application Core │
|
|
│ ┌───────────────────────────────────────┐ │
|
|
│ │ Domain Models │ │
|
|
│ │ (Project, Command, APIKey, Scope) │ │
|
|
│ └───────────────────────────────────────┘ │
|
|
│ ┌───────────────────────────────────────┐ │
|
|
│ │ Port Interfaces │ │
|
|
│ │ (ProjectRepository, Executor, etc.) │ │
|
|
│ └───────────────────────────────────────┘ │
|
|
│ ┌───────────────────────────────────────┐ │
|
|
│ │ Service Layer │ │
|
|
│ │ (ProjectService, uses ports) │ │
|
|
│ └───────────────────────────────────────┘ │
|
|
└───────────────────┬─────────────────────────┘
|
|
│
|
|
┌───────────────────┴─────────────────────────┐
|
|
│ Adapters │
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Kubernetes │ │ Postgres │ │
|
|
│ │ Adapter │ │ Adapter │ │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Key Flows
|
|
|
|
1. **Command Execution**: Client -> Handler -> Service -> Executor -> K8s Pod
|
|
2. **SSE Streaming**: Command output -> StreamManager -> SSE Response
|
|
3. **Authentication**: Request -> Middleware -> AuthService -> DB Lookup
|
|
|
|
See [streaming.md](streaming.md) and [security.md](security.md) for details.
|
|
|
|
## Technology Stack
|
|
|
|
| Component | Technology |
|
|
|-----------|------------|
|
|
| Language | Go 1.22+ |
|
|
| HTTP Router | chi v5 |
|
|
| Database | PostgreSQL |
|
|
| Container Orchestration | Kubernetes |
|
|
| Metrics | Prometheus |
|
|
| Tracing | OpenTelemetry (optional) |
|
|
|
|
## Package Structure
|
|
|
|
```
|
|
internal/
|
|
├── adapter/ # Infrastructure adapters
|
|
│ ├── cached/ # Caching wrappers
|
|
│ └── kubernetes/ # K8s client implementation
|
|
├── auth/ # Authentication & authorization
|
|
├── circuitbreaker/ # Circuit breaker for resilience
|
|
├── db/ # Database connectivity
|
|
├── domain/ # Core domain models
|
|
├── handlers/ # HTTP handlers
|
|
├── metrics/ # Prometheus metrics
|
|
├── port/ # Port interfaces (abstractions)
|
|
├── ratelimit/ # Rate limiting
|
|
├── sanitize/ # Command sanitization
|
|
├── service/ # Business logic services
|
|
└── validate/ # Input validation
|
|
|
|
pkg/
|
|
└── api/ # Shared API utilities
|
|
|
|
cmd/
|
|
└── rdev-api/ # Main application entry point
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Environment variables:
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `PORT` | HTTP server port | 8080 |
|
|
| `POSTGRES_HOST` | Database host | postgres.databases.svc |
|
|
| `POSTGRES_DB` | Database name | rdev |
|
|
| `RDEV_NAMESPACE` | K8s namespace for pods | default |
|
|
| `RATE_LIMIT_RPS` | Requests per second limit | 10 |
|
|
| `CONCURRENT_COMMANDS` | Max concurrent commands | 5 |
|
|
|
|
## Related Documentation
|
|
|
|
- [Hexagonal Architecture](hexagonal.md) - Port/Adapter pattern details
|
|
- [Security](security.md) - Auth, sanitization, rate limiting
|
|
- [Streaming](streaming.md) - SSE protocol, reconnection handling
|