jordan 72d16929ca feat: Implement hexagonal architecture with services, webhooks, queue, and telemetry

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>

2026-01-25 19:57:46 -07:00

7.3 KiB

Raw Blame History

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 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

Command Execution: Client -> Handler -> Service -> Executor -> K8s Pod
SSE Streaming: Command output -> StreamManager -> SSE Response
Authentication: Request -> Middleware -> AuthService -> DB Lookup

See streaming.md and 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

Hexagonal Architecture - Port/Adapter pattern details
Security - Auth, sanitization, rate limiting
Streaming - SSE protocol, reconnection handling

7.3 KiB Raw Blame History