docs: add agent endpoint specifications for mod management and metrics (Phase 1)
This commit is contained in:
parent
81c1a39584
commit
db5f66fbcb
403
Agent_Endpoint_Specifications_Phase1.md
Normal file
403
Agent_Endpoint_Specifications_Phase1.md
Normal file
@ -0,0 +1,403 @@
|
||||
# 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)
|
||||
Loading…
Reference in New Issue
Block a user