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

2.9 KiB

Raw Blame History

rdev API Documentation

rdev provides a REST API for remote development environments with SSE streaming support.

Quick Start

1. Get an API Key

Contact your administrator to get an API key, or create one if you have admin access:

curl -X POST https://rdev.example.com/keys \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-key",
    "scopes": ["projects:read", "projects:execute"]
  }'

2. List Projects

curl https://rdev.example.com/projects \
  -H "X-API-Key: your-key"

3. Execute a Command

curl -X POST https://rdev.example.com/projects/my-project/shell \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'

4. Stream Output

curl -N https://rdev.example.com/projects/my-project/events?stream_id=cmd-001 \
  -H "X-API-Key: your-key"

Base URL

https://rdev.example.com

Authentication

See authentication.md for details.

All requests (except /health, /ready, /metrics) require authentication.

Header:

X-API-Key: rdev_xxxx...

Or:

Authorization: Bearer rdev_xxxx...

Endpoints

Method	Path	Description
GET	`/projects`	List all projects
GET	`/projects/{id}`	Get project details
POST	`/projects/{id}/claude`	Run Claude command
POST	`/projects/{id}/shell`	Run shell command
POST	`/projects/{id}/git`	Run git command
GET	`/projects/{id}/events`	SSE event stream
GET	`/keys`	List API keys
POST	`/keys`	Create API key
DELETE	`/keys/{id}`	Revoke API key
GET	`/health`	Liveness check
GET	`/ready`	Readiness check
GET	`/metrics`	Prometheus metrics

Response Format

All responses follow this format:

Success

{
  "data": { ... },
  "meta": {
    "request_id": "req-abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found: my-project"
  },
  "meta": {
    "request_id": "req-abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	HTTP Status	Description
`BAD_REQUEST`	400	Invalid request body or parameters
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`TOO_MANY_REQUESTS`	429	Rate limit exceeded
`INTERNAL_ERROR`	500	Server error

Rate Limiting

Requests are rate limited per API key:

Limit Type	Default
Requests/second	10
Concurrent commands	5

Headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1642089600

2.9 KiB Raw Blame History