mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 22:34:56 +00:00
474 lines
14 KiB
Markdown
474 lines
14 KiB
Markdown
# C++ DBAL Daemon (Phase 3 - Future)
|
|
|
|
## Overview
|
|
|
|
The C++ daemon provides a secure, sandboxed database access layer that isolates credentials and enforces strict access control. This is designed for deployment beyond GitHub Spark's constraints.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ DBAL Daemon (C++ Binary) │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────┐ │
|
|
│ │ WebSocket Server (Port 50051) │ │
|
|
│ │ - TLS/SSL enabled │ │
|
|
│ │ - Authentication required │ │
|
|
│ │ - Rate limiting │ │
|
|
│ └──────────────────┬─────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────▼─────────────────────────────┐ │
|
|
│ │ RPC Message Handler │ │
|
|
│ │ - Parse JSON-RPC messages │ │
|
|
│ │ - Validate requests │ │
|
|
│ │ - Route to correct handler │ │
|
|
│ └──────────────────┬─────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────▼─────────────────────────────┐ │
|
|
│ │ ACL Enforcement Layer │ │
|
|
│ │ - Check user permissions │ │
|
|
│ │ - Apply row-level filters │ │
|
|
│ │ - Log all operations │ │
|
|
│ └──────────────────┬─────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────▼─────────────────────────────┐ │
|
|
│ │ Query Executor │ │
|
|
│ │ - Build safe SQL queries │ │
|
|
│ │ - Parameterized statements │ │
|
|
│ │ - Transaction support │ │
|
|
│ └──────────────────┬─────────────────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────────────────▼─────────────────────────────┐ │
|
|
│ │ Database Adapters │ │
|
|
│ │ - PostgreSQL (libpq) │ │
|
|
│ │ - SQLite (sqlite3) │ │
|
|
│ │ - MySQL (mysqlclient) │ │
|
|
│ │ - Native Prisma Bridge │ │
|
|
│ └──────────────────┬─────────────────────────────┘ │
|
|
│ │ │
|
|
└─────────────────────┼────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌───────────────┐
|
|
│ Database │
|
|
└───────────────┘
|
|
```
|
|
|
|
> **Phase 3 status:** The diagrams above describe the future state; the current C++ build still wires to the in-memory store (`dbal/cpp/src/store/in_memory_store.hpp`), so the PostgreSQL/MySQL adapters shown here are aspirational and not shipped yet. Rely on the TypeScript `PrismaAdapter`, `PostgresAdapter`, or `MySQLAdapter` for production workloads today.
|
|
|
|
## Security Features
|
|
|
|
### 1. Process Isolation
|
|
- Runs as separate process with restricted permissions
|
|
- Cannot access filesystem outside designated directories
|
|
- Network access limited to database connections only
|
|
- No shell access or command execution
|
|
|
|
### 2. Credential Protection
|
|
- Database credentials stored in secure config file
|
|
- Config file readable only by daemon process
|
|
- Credentials never exposed to client applications
|
|
- Support for encrypted credential storage
|
|
|
|
### 3. Sandboxed Execution
|
|
- All queries validated before execution
|
|
- Parameterized queries only (no SQL injection)
|
|
- Query complexity limits (prevent DoS)
|
|
- Timeout enforcement (30s default)
|
|
|
|
### 4. Audit Logging
|
|
- All operations logged with:
|
|
- Timestamp
|
|
- User ID
|
|
- Operation type
|
|
- Entity affected
|
|
- Success/failure
|
|
- Error details
|
|
- Logs written to secure location
|
|
- Log rotation and retention policies
|
|
|
|
### 5. Access Control
|
|
- Row-level security enforcement
|
|
- Operation-level permissions
|
|
- Rate limiting per user
|
|
- Session validation
|
|
|
|
## Build Requirements
|
|
|
|
### Dependencies
|
|
- C++17 or later
|
|
- CMake 3.20+
|
|
- OpenSSL 1.1+
|
|
- libpq (PostgreSQL client)
|
|
- sqlite3
|
|
- Boost.Beast (WebSocket)
|
|
|
|
### Building
|
|
```bash
|
|
cd dbal/cpp
|
|
mkdir build && cd build
|
|
cmake ..
|
|
make -j$(nproc)
|
|
```
|
|
|
|
### Running
|
|
```bash
|
|
./dbal_daemon --config=../config/production.yaml
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Example Config (YAML)
|
|
```yaml
|
|
server:
|
|
host: "0.0.0.0"
|
|
port: 50051
|
|
tls:
|
|
enabled: true
|
|
cert_file: "/etc/dbal/server.crt"
|
|
key_file: "/etc/dbal/server.key"
|
|
ca_file: "/etc/dbal/ca.crt"
|
|
|
|
database:
|
|
adapter: "postgresql"
|
|
connection:
|
|
host: "db.example.com"
|
|
port: 5432
|
|
database: "metabuilder"
|
|
user: "dbal_service"
|
|
password: "${DBAL_DB_PASSWORD}" # From environment
|
|
ssl_mode: "require"
|
|
pool_size: 20
|
|
timeout: 30000
|
|
|
|
security:
|
|
sandbox: "strict"
|
|
audit_log: true
|
|
audit_log_path: "/var/log/dbal/audit.log"
|
|
rate_limit:
|
|
enabled: true
|
|
requests_per_minute: 100
|
|
burst: 20
|
|
|
|
acl:
|
|
rules_file: "/etc/dbal/acl_rules.yaml"
|
|
cache_ttl: 300
|
|
|
|
performance:
|
|
query_timeout: 30000
|
|
max_query_complexity: 1000
|
|
connection_pool_size: 20
|
|
cache_enabled: true
|
|
cache_size_mb: 256
|
|
```
|
|
|
|
## Protocol
|
|
|
|
### WebSocket JSON-RPC
|
|
|
|
#### Request Format
|
|
```json
|
|
{
|
|
"id": "req_12345",
|
|
"method": "create",
|
|
"params": [
|
|
"User",
|
|
{
|
|
"username": "alice",
|
|
"email": "alice@example.com",
|
|
"role": "user"
|
|
}
|
|
],
|
|
"auth": {
|
|
"token": "session_token_here",
|
|
"user_id": "user_123"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Response Format (Success)
|
|
```json
|
|
{
|
|
"id": "req_12345",
|
|
"result": {
|
|
"id": "user_456",
|
|
"username": "alice",
|
|
"email": "alice@example.com",
|
|
"role": "user",
|
|
"createdAt": "2024-01-15T10:30:00Z",
|
|
"updatedAt": "2024-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Response Format (Error)
|
|
```json
|
|
{
|
|
"id": "req_12345",
|
|
"error": {
|
|
"code": 403,
|
|
"message": "Access forbidden",
|
|
"details": {
|
|
"reason": "Insufficient permissions for operation 'create' on entity 'User'"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Supported Methods
|
|
- `create(entity, data)` - Create new record
|
|
- `read(entity, id)` - Read record by ID
|
|
- `update(entity, id, data)` - Update record
|
|
- `delete(entity, id)` - Delete record
|
|
- `list(entity, options)` - List records with filters
|
|
- `getCapabilities()` - Query adapter capabilities
|
|
|
|
## Deployment Options
|
|
|
|
### 1. Docker Container
|
|
|
|
```dockerfile
|
|
FROM ubuntu:22.04
|
|
|
|
RUN apt-get update && apt-get install -y \
|
|
libpq5 \
|
|
libsqlite3-0 \
|
|
libssl3 \
|
|
libboost-system1.74.0
|
|
|
|
COPY build/dbal_daemon /usr/local/bin/
|
|
COPY config/production.yaml /etc/dbal/config.yaml
|
|
|
|
USER dbal
|
|
EXPOSE 50051
|
|
|
|
CMD ["/usr/local/bin/dbal_daemon", "--config=/etc/dbal/config.yaml"]
|
|
```
|
|
|
|
### 2. Systemd Service
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=DBAL Daemon
|
|
After=network.target postgresql.service
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=dbal
|
|
Group=dbal
|
|
ExecStart=/usr/local/bin/dbal_daemon --config=/etc/dbal/config.yaml
|
|
Restart=on-failure
|
|
RestartSec=5s
|
|
|
|
# Security hardening
|
|
NoNewPrivileges=true
|
|
PrivateTmp=true
|
|
ProtectSystem=strict
|
|
ProtectHome=true
|
|
ReadWritePaths=/var/log/dbal
|
|
ProtectKernelTunables=true
|
|
ProtectKernelModules=true
|
|
ProtectControlGroups=true
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
### 3. Kubernetes Deployment
|
|
|
|
```yaml
|
|
apiVersion: apps/v1
|
|
kind: Deployment
|
|
metadata:
|
|
name: dbal-daemon
|
|
spec:
|
|
replicas: 3
|
|
selector:
|
|
matchLabels:
|
|
app: dbal-daemon
|
|
template:
|
|
metadata:
|
|
labels:
|
|
app: dbal-daemon
|
|
spec:
|
|
containers:
|
|
- name: dbal
|
|
image: your-registry/dbal-daemon:latest
|
|
ports:
|
|
- containerPort: 50051
|
|
name: websocket
|
|
env:
|
|
- name: DBAL_DB_PASSWORD
|
|
valueFrom:
|
|
secretKeyRef:
|
|
name: dbal-secrets
|
|
key: db-password
|
|
volumeMounts:
|
|
- name: config
|
|
mountPath: /etc/dbal
|
|
readOnly: true
|
|
- name: logs
|
|
mountPath: /var/log/dbal
|
|
resources:
|
|
requests:
|
|
memory: "256Mi"
|
|
cpu: "250m"
|
|
limits:
|
|
memory: "512Mi"
|
|
cpu: "500m"
|
|
livenessProbe:
|
|
tcpSocket:
|
|
port: 50051
|
|
initialDelaySeconds: 10
|
|
periodSeconds: 10
|
|
readinessProbe:
|
|
tcpSocket:
|
|
port: 50051
|
|
initialDelaySeconds: 5
|
|
periodSeconds: 5
|
|
volumes:
|
|
- name: config
|
|
configMap:
|
|
name: dbal-config
|
|
- name: logs
|
|
emptyDir: {}
|
|
---
|
|
apiVersion: v1
|
|
kind: Service
|
|
metadata:
|
|
name: dbal-daemon
|
|
spec:
|
|
selector:
|
|
app: dbal-daemon
|
|
ports:
|
|
- port: 50051
|
|
targetPort: 50051
|
|
name: websocket
|
|
type: ClusterIP
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
### Health Check Endpoint
|
|
```
|
|
GET /health
|
|
Response: 200 OK
|
|
{
|
|
"status": "healthy",
|
|
"version": "1.0.0",
|
|
"uptime": 3600,
|
|
"connections": {
|
|
"active": 15,
|
|
"total": 243
|
|
},
|
|
"database": {
|
|
"connected": true,
|
|
"latency_ms": 2.5
|
|
}
|
|
}
|
|
```
|
|
|
|
### Metrics (Prometheus Format)
|
|
```
|
|
# HELP dbal_requests_total Total number of requests
|
|
# TYPE dbal_requests_total counter
|
|
dbal_requests_total{method="create",status="success"} 1234
|
|
dbal_requests_total{method="read",status="success"} 5678
|
|
dbal_requests_total{method="update",status="error"} 12
|
|
|
|
# HELP dbal_request_duration_seconds Request duration in seconds
|
|
# TYPE dbal_request_duration_seconds histogram
|
|
dbal_request_duration_seconds_bucket{method="create",le="0.005"} 1000
|
|
dbal_request_duration_seconds_bucket{method="create",le="0.01"} 1200
|
|
dbal_request_duration_seconds_bucket{method="create",le="0.025"} 1234
|
|
|
|
# HELP dbal_active_connections Active database connections
|
|
# TYPE dbal_active_connections gauge
|
|
dbal_active_connections 15
|
|
|
|
# HELP dbal_acl_checks_total Total ACL checks performed
|
|
# TYPE dbal_acl_checks_total counter
|
|
dbal_acl_checks_total{result="allowed"} 9876
|
|
dbal_acl_checks_total{result="denied"} 123
|
|
```
|
|
|
|
## Performance
|
|
|
|
### Benchmarks
|
|
| Operation | Direct DB | Via Daemon | Overhead |
|
|
|-----------|-----------|------------|----------|
|
|
| SELECT | 2ms | 2.5ms | +25% |
|
|
| INSERT | 3ms | 3.5ms | +17% |
|
|
| UPDATE | 3ms | 3.5ms | +17% |
|
|
| DELETE | 2ms | 2.5ms | +25% |
|
|
| JOIN | 15ms | 16ms | +7% |
|
|
| Bulk (100)| 50ms | 52ms | +4% |
|
|
|
|
### Optimization
|
|
- Connection pooling (20 connections default)
|
|
- Query result caching (256MB default)
|
|
- Prepared statement reuse
|
|
- Batch operation support
|
|
|
|
## Security Hardening Checklist
|
|
|
|
- [ ] Run as non-root user
|
|
- [ ] Use TLS for all connections
|
|
- [ ] Rotate credentials regularly
|
|
- [ ] Enable audit logging
|
|
- [ ] Set up log monitoring/alerting
|
|
- [ ] Implement rate limiting
|
|
- [ ] Use prepared statements only
|
|
- [ ] Validate all inputs
|
|
- [ ] Sandbox process execution
|
|
- [ ] Regular security audits
|
|
- [ ] Keep dependencies updated
|
|
- [ ] Monitor for suspicious activity
|
|
|
|
## Limitations
|
|
|
|
### Not Suitable for GitHub Spark
|
|
The C++ daemon requires:
|
|
- Native binary execution
|
|
- System-level process management
|
|
- Port binding and network access
|
|
- Filesystem access for logs/config
|
|
- Long-running process lifecycle
|
|
|
|
GitHub Spark does not support these requirements, which is why Phase 2 uses TypeScript with the same architecture pattern.
|
|
|
|
### Future Deployment Targets
|
|
- ✅ Docker containers
|
|
- ✅ Kubernetes clusters
|
|
- ✅ VM instances (AWS EC2, GCP Compute Engine, etc.)
|
|
- ✅ Bare metal servers
|
|
- ✅ Platform services (AWS ECS, GCP Cloud Run, etc.)
|
|
- ❌ GitHub Spark (browser-based environment)
|
|
- ❌ Serverless functions (too slow for C++ cold starts)
|
|
|
|
## Migration from Phase 2
|
|
|
|
1. **Deploy daemon** to your infrastructure
|
|
2. **Update client config** to point to daemon endpoint
|
|
3. **Switch mode** from 'development' to 'production'
|
|
4. **Test thoroughly** before full rollout
|
|
5. **Monitor performance** and adjust as needed
|
|
|
|
```typescript
|
|
// Phase 2 (Development)
|
|
const client = new DBALClient({
|
|
mode: 'development',
|
|
adapter: 'prisma'
|
|
})
|
|
|
|
// Phase 3 (Production with Daemon)
|
|
const client = new DBALClient({
|
|
mode: 'production',
|
|
endpoint: 'wss://dbal.yourcompany.com:50051'
|
|
})
|
|
```
|
|
|
|
## Summary
|
|
|
|
The C++ daemon provides maximum security and performance for production deployments outside GitHub Spark. Phase 2's TypeScript implementation uses the same architecture and can seamlessly migrate when the daemon becomes available.
|