404 lines
9.1 KiB
Markdown
404 lines
9.1 KiB
Markdown
# Agent Endpoint Specifications - Phase 1 Release
|
|
|
|
**Last Updated**: February 21, 2026
|
|
**Status**: Active Development
|
|
**Target**: Pre-Launch Release
|
|
|
|
---
|
|
|
|
## 📋 Current Agent Capabilities (Baseline)
|
|
|
|
**Already Implemented**:
|
|
- ✅ Provisioning (dev + game containers)
|
|
- ✅ Lifecycle control (`/start`, `/stop`, `/restart`)
|
|
- ✅ State reporting (`/status`, `/health`)
|
|
- ✅ PTY-backed WebSocket console (`/console/stream`)
|
|
- ✅ Minecraft player telemetry (`/game/players`)
|
|
- ✅ Self-update system (`/agent/update`, `/agent/update/status`)
|
|
- ✅ Version endpoint (`/version`)
|
|
- ✅ Autostart subsystem
|
|
- ✅ Periodic update checks (notify/auto/off modes)
|
|
|
|
---
|
|
|
|
## 🎯 New Endpoints for Phase 1
|
|
|
|
### **Priority 1: Mod Management (CRITICAL - Blocking Release)**
|
|
|
|
#### **GET /game/mods** - Mod Detection
|
|
|
|
**Purpose**: List all installed mods with metadata
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"variant": "forge",
|
|
"variant_version": "47.2.0",
|
|
"minecraft_version": "1.20.1",
|
|
"mods": [
|
|
{
|
|
"id": "jei",
|
|
"name": "Just Enough Items",
|
|
"version": "15.2.0.27",
|
|
"filename": "jei-1.20.1-forge-15.2.0.27.jar",
|
|
"description": "Item and recipe viewing mod",
|
|
"required": false,
|
|
"server_side": true,
|
|
"client_side": true,
|
|
"dependencies": ["minecraft@1.20.1", "forge@>=47.0.0"],
|
|
"enabled": true,
|
|
"source": "curated"
|
|
}
|
|
],
|
|
"total_count": 1,
|
|
"scan_timestamp": "2026-02-21T16:00:00Z"
|
|
}
|
|
```
|
|
|
|
**Implementation Requirements**:
|
|
- Scan `/server/mods/` directory for .jar files
|
|
- Detect variant by checking for:
|
|
- Forge: `/server/config/forge-*.toml` or `META-INF/mods.toml` in JARs
|
|
- Fabric: `/server/fabric.mod.json` or `fabric.mod.json` in JARs
|
|
- Paper: `/server/plugins/*.jar` exists
|
|
- Parse metadata from:
|
|
- **Forge**: `META-INF/mods.toml` or `mcmod.info`
|
|
- **Fabric**: `fabric.mod.json`
|
|
- **Paper**: `plugin.yml`
|
|
- Cache results for 5-10 minutes
|
|
- Gracefully handle missing/corrupt metadata (fallback to filename)
|
|
|
|
---
|
|
|
|
#### **POST /game/mods/install** - Install Curated Mod
|
|
|
|
**Purpose**: Download and install mod from curated artifact store
|
|
|
|
**Request**:
|
|
```json
|
|
{
|
|
"source": "curated",
|
|
"mod_id": "jei",
|
|
"version": "15.2.0.27",
|
|
"artifact_url": "https://artifacts.zerolaghub.com/mods/forge/jei-15.2.0.27.jar",
|
|
"artifact_hash": "sha256:abc123..."
|
|
}
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"mod": { /* full mod object */ },
|
|
"action": "installed",
|
|
"restart_required": true
|
|
}
|
|
```
|
|
|
|
**Implementation Requirements**:
|
|
- Download from `artifact_url` to temp directory
|
|
- **Verify SHA-256 hash matches `artifact_hash`** (CRITICAL - security)
|
|
- Only accept URLs from `artifacts.zerolaghub.com` domain
|
|
- Drop privileges to minecraft user before file operations
|
|
- Move verified file to `/server/mods/{filename}`
|
|
- Set permissions: owner=minecraft, mode=0644
|
|
- Return error if hash mismatch
|
|
- Return error if disk full
|
|
|
|
**Security (Non-Negotiable)**:
|
|
```go
|
|
// Example secure implementation pattern:
|
|
// 1. Download to /tmp/
|
|
// 2. Verify hash
|
|
// 3. If valid, install as minecraft user
|
|
exec.Command("su", "-", "minecraft", "-c",
|
|
"cp /tmp/verified-mod.jar /server/mods/mod.jar").Run()
|
|
```
|
|
|
|
---
|
|
|
|
#### **PATCH /game/mods/:mod_id** - Enable/Disable Mod
|
|
|
|
**Purpose**: Toggle mod enabled state without removing
|
|
|
|
**Request**:
|
|
```json
|
|
{
|
|
"enabled": false
|
|
}
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"mod": { /* updated mod object */ },
|
|
"action": "disabled",
|
|
"restart_required": true
|
|
}
|
|
```
|
|
|
|
**Implementation**:
|
|
- Disable: Rename `.jar` → `.jar.disabled`
|
|
- Enable: Rename `.jar.disabled` → `.jar`
|
|
- Alternative: Move to `/server/mods-disabled/` directory
|
|
|
|
---
|
|
|
|
#### **DELETE /game/mods/:mod_id** - Remove Mod
|
|
|
|
**Purpose**: Permanently remove mod
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"action": "removed",
|
|
"restart_required": true
|
|
}
|
|
```
|
|
|
|
**Implementation**:
|
|
- Delete `.jar` file from `/server/mods/`
|
|
- Optional: Move to `/server/mods-removed/` for rollback capability
|
|
|
|
---
|
|
|
|
### **Priority 2: Process Metrics (HIGH)**
|
|
|
|
#### **GET /metrics/process** - Game Process Stats
|
|
|
|
**Purpose**: Expose game server process metrics
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"process": {
|
|
"pid": 12345,
|
|
"status": "running",
|
|
"uptime_seconds": 3600,
|
|
"restart_count": 2,
|
|
"last_start": "2026-02-21T15:30:00Z",
|
|
"last_crash": "2026-02-21T12:00:00Z"
|
|
},
|
|
"memory": {
|
|
"rss_bytes": 2147483648,
|
|
"vms_bytes": 4294967296
|
|
}
|
|
}
|
|
```
|
|
|
|
**Implementation**:
|
|
- Read from `/proc/{pid}/stat` and `/proc/{pid}/status`
|
|
- Track restart count in state file
|
|
- Return 404 if process not running (not an error)
|
|
|
|
---
|
|
|
|
### **Priority 3: Agent Health (MEDIUM)**
|
|
|
|
#### **GET /metrics/agent** - Agent Health
|
|
|
|
**Purpose**: Expose agent operational metrics
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"agent": {
|
|
"version": "v1.2.3",
|
|
"uptime_seconds": 86400,
|
|
"last_update_check": "2026-02-21T14:00:00Z",
|
|
"update_available": false
|
|
},
|
|
"handlers": {
|
|
"console_sessions": 2,
|
|
"active_websockets": 3,
|
|
"provisioning_active": false
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### **Priority 4: Provisioning Progress (LOW)**
|
|
|
|
#### **GET /metrics/provisioning** - Install Progress
|
|
|
|
**Purpose**: Real-time provisioning status
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"active": true,
|
|
"current_step": "downloading_artifacts",
|
|
"progress_percent": 45,
|
|
"started_at": "2026-02-21T15:00:00Z",
|
|
"estimated_completion": "2026-02-21T15:10:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 Security Requirements (CRITICAL)
|
|
|
|
### **Privilege Separation**
|
|
|
|
**MUST**: All mod file operations run as non-root user
|
|
|
|
```
|
|
✅ DO: Use su/sudo to drop privileges
|
|
❌ DON'T: Write files as root
|
|
```
|
|
|
|
### **Hash Verification**
|
|
|
|
**MUST**: Verify SHA-256 before installing curated mods
|
|
|
|
```
|
|
Process:
|
|
1. Download to temp directory
|
|
2. Calculate SHA-256 hash
|
|
3. Compare with expected hash
|
|
4. If match → install
|
|
5. If mismatch → delete and error
|
|
```
|
|
|
|
### **URL Whitelisting**
|
|
|
|
**MUST**: Only download from trusted domains
|
|
|
|
```
|
|
Allowed:
|
|
✅ artifacts.zerolaghub.com
|
|
|
|
Rejected:
|
|
❌ Arbitrary URLs
|
|
❌ User-provided URLs
|
|
❌ External mod sites (Phase 2)
|
|
```
|
|
|
|
### **Container Isolation**
|
|
|
|
**Verify**:
|
|
- Game server runs as non-root user (minecraft/gameserver)
|
|
- LXC containers are unprivileged
|
|
- Network segmentation active (10.200.0.0/24 VLAN)
|
|
|
|
---
|
|
|
|
## 📦 Suggested Go Package Structure
|
|
|
|
```
|
|
internal/
|
|
├── mods/
|
|
│ ├── scanner.go // Directory scanning
|
|
│ ├── forge.go // Forge metadata parser
|
|
│ ├── fabric.go // Fabric metadata parser
|
|
│ ├── paper.go // Paper plugin parser
|
|
│ ├── installer.go // Download + install logic
|
|
│ └── types.go // Structs and enums
|
|
├── metrics/
|
|
│ ├── process.go // Game process metrics
|
|
│ ├── agent.go // Agent health metrics
|
|
│ └── provisioning.go // Provisioning progress
|
|
└── handlers/
|
|
├── game.go // Mod endpoints
|
|
└── metrics.go // Metrics endpoints
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Implementation Priority
|
|
|
|
### **Week 1: Mod Detection + Install**
|
|
1. `GET /game/mods` with .jar listing
|
|
2. Forge metadata parsing
|
|
3. `POST /game/mods/install` with hash verification
|
|
4. Test with 5-10 mods
|
|
|
|
### **Week 2: Mod Management**
|
|
1. `PATCH /game/mods/:id` (enable/disable)
|
|
2. `DELETE /game/mods/:id` (remove)
|
|
3. Fabric metadata parsing
|
|
4. Paper plugin parsing
|
|
|
|
### **Week 3: Metrics**
|
|
1. `GET /metrics/process`
|
|
2. `GET /metrics/agent`
|
|
3. Optional: `GET /metrics/provisioning`
|
|
|
|
---
|
|
|
|
## 🚫 Phase 2 Features (NOT Phase 1)
|
|
|
|
**Defer These**:
|
|
- ❌ User upload handling (requires malware scanning)
|
|
- ❌ Dependency resolution
|
|
- ❌ Mod update checking
|
|
- ❌ Config file management
|
|
- ❌ Rollback/restore functionality
|
|
- ❌ Dev container → Game server transfer
|
|
|
|
---
|
|
|
|
## 🧪 Testing Requirements
|
|
|
|
### **Mod Detection**:
|
|
- Empty directory → Empty array
|
|
- Forge mods → Correct parsing
|
|
- Fabric mods → Correct parsing
|
|
- Paper plugins → Correct parsing
|
|
- Corrupt metadata → Graceful fallback
|
|
- Mixed types → Correct variant detection
|
|
|
|
### **Mod Installation**:
|
|
- Valid hash → Success
|
|
- Invalid hash → Error, no install
|
|
- Network failure → Error, no corruption
|
|
- Disk full → Error
|
|
- Invalid URL → Rejection
|
|
|
|
### **Security**:
|
|
- File ops run as minecraft user
|
|
- Hash mismatch prevents install
|
|
- Malformed requests don't crash agent
|
|
|
|
---
|
|
|
|
## 📊 API Integration
|
|
|
|
**API Will**:
|
|
- Cache `GET /game/mods` responses
|
|
- Validate user ownership before agent calls
|
|
- Handle authentication/authorization
|
|
- Aggregate metrics with Prometheus data
|
|
|
|
**Agent Doesn't Handle**:
|
|
- User authentication (API's job)
|
|
- Ownership validation (API's job)
|
|
- Billing (API's job)
|
|
- Frontend concerns (API's job)
|
|
|
|
---
|
|
|
|
## ✅ Definition of Done
|
|
|
|
**Phase 1 Complete When**:
|
|
- ✅ All mod variants parse correctly (Forge/Fabric/Paper)
|
|
- ✅ Hash verification prevents tampered artifacts
|
|
- ✅ Mod enable/disable/remove works
|
|
- ✅ Process metrics accurate
|
|
- ✅ All file operations use dropped privileges
|
|
- ✅ Tests pass for all scenarios
|
|
- ✅ Error handling graceful (no crashes)
|
|
- ✅ Integration with API tested
|
|
|
|
---
|
|
|
|
## 🔗 Related Documentation
|
|
|
|
- **API Integration**: See `game.js` endpoint specifications
|
|
- **Security Model**: See Drift Prevention Card DEC-008
|
|
- **Container Architecture**: See Infrastructure documentation
|
|
- **Mod Catalog**: See artifact store structure (to be documented)
|