263 lines
6.2 KiB
Markdown
263 lines
6.2 KiB
Markdown
# ZeroLagHub – Dev → Game Artifact Promotion Pipeline
|
||
|
||
**Version:** 1.0
|
||
**Phase:** Phase 2 Foundation *(after Dynamic Mod Install is stable)*
|
||
**Applies To:** Dev Containers + Game Containers
|
||
**Owner:** Control Plane (API) + Agent
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
Define a structured, opt-in pipeline that allows:
|
||
|
||
- A Dev container to produce mod artifacts
|
||
- A linked Game container to receive those artifacts
|
||
- Safe deployment with automatic recovery
|
||
- Zero manual file transfer
|
||
- Zero SSH requirement
|
||
|
||
This creates a CI-like promotion workflow inside ZeroLagHub.
|
||
|
||
---
|
||
|
||
## 2. Architectural Principles
|
||
|
||
- Dev and Game containers remain isolated at all times
|
||
- All transfers occur through API orchestration
|
||
- No container-to-container direct access
|
||
- Promotion is explicit and opt-in
|
||
- Dev artifacts are treated as experimental
|
||
- Deployment safety system (see `mod-deployment-safety.md`) applies automatically
|
||
|
||
---
|
||
|
||
## 3. Linking Model (Opt-In)
|
||
|
||
### 3.1 Link Requirement
|
||
|
||
A Dev container must be explicitly linked to a Game container before promotion is possible.
|
||
|
||
Linking is:
|
||
- Optional
|
||
- One Dev → One Game (Phase 1)
|
||
- Same customer only
|
||
- Enforced and validated by the API
|
||
|
||
### 3.2 Database Schema
|
||
|
||
```
|
||
DevGameLink
|
||
------------
|
||
id
|
||
devContainerId
|
||
gameContainerId
|
||
createdAt
|
||
```
|
||
|
||
**Constraints:**
|
||
- `devContainer.type = "dev"`
|
||
- `gameContainer.type = "game"`
|
||
- Same owner on both containers
|
||
- No circular linking
|
||
|
||
---
|
||
|
||
## 4. Dev Artifact Directory Contract
|
||
|
||
Inside the Dev container, all promotable artifacts must reside at:
|
||
|
||
```
|
||
/opt/zlh/dev-artifacts/
|
||
```
|
||
|
||
**Requirements:**
|
||
- Only `.jar` files are eligible for promotion
|
||
- Agent must expose an artifact listing endpoint over this directory
|
||
- Directory must not allow execution of contained files
|
||
- No recursive scanning outside this directory
|
||
|
||
Build tooling templates should direct mod output to this path.
|
||
|
||
---
|
||
|
||
## 5. Dev Agent Endpoints
|
||
|
||
### 5.1 List Artifacts
|
||
|
||
```
|
||
GET /dev/artifacts
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "coolmod-1.0.0.jar",
|
||
"size": 123456,
|
||
"modifiedAt": "2026-02-22T00:00:00Z",
|
||
"sha256": "abc123..."
|
||
}
|
||
]
|
||
```
|
||
|
||
### 5.2 Stream Artifact
|
||
|
||
```
|
||
GET /dev/artifacts/download?name=coolmod-1.0.0.jar
|
||
```
|
||
|
||
Used by the API to pull the artifact binary for transfer to the Game agent. The Dev agent does not push directly.
|
||
|
||
---
|
||
|
||
## 6. Promotion Flow
|
||
|
||
### 6.1 User Action
|
||
|
||
On the Dev server page, the user:
|
||
|
||
1. Selects an artifact from the `/opt/zlh/dev-artifacts/` listing
|
||
2. Clicks **"Deploy to Linked Game Server"**
|
||
|
||
### 6.2 API Orchestration
|
||
|
||
The API must:
|
||
|
||
1. Validate the `DevGameLink` exists
|
||
2. Validate ownership of both containers
|
||
3. Fetch artifact metadata from Dev agent (`GET /dev/artifacts`)
|
||
4. Stream artifact binary from Dev agent (`GET /dev/artifacts/download`)
|
||
5. Call Game agent:
|
||
|
||
```
|
||
POST /game/mods/install/dev
|
||
```
|
||
|
||
Payload includes:
|
||
- `filename`
|
||
- `sha256`
|
||
- Artifact binary stream
|
||
|
||
### 6.3 Game Agent Handling
|
||
|
||
Upon receiving the promotion request, the Game agent must:
|
||
|
||
1. Stop the game server
|
||
2. Create a snapshot (`mods/` + `config/` only — see `mod-deployment-safety.md`)
|
||
3. Create a shadow copy if replacing an existing mod with the same name
|
||
4. Place the artifact into `mods/dev/`
|
||
5. Restart the server
|
||
6. Enter the stabilization window
|
||
7. Apply self-healing logic automatically if instability is detected
|
||
|
||
---
|
||
|
||
## 7. Mod Channel Separation
|
||
|
||
Game containers must logically separate mods by source:
|
||
|
||
```
|
||
mods/
|
||
curated/ ← Modrinth installs only
|
||
dev/ ← Dev promotion installs only
|
||
```
|
||
|
||
**Rules:**
|
||
- Dev promotions write exclusively to `mods/dev/`
|
||
- Modrinth installs write exclusively to `mods/curated/`
|
||
- The mod loader must read from both (via symlink flatten or equivalent strategy)
|
||
- No cross-channel writes permitted
|
||
|
||
---
|
||
|
||
## 8. Failure Handling
|
||
|
||
All deployment safety rules defined in [`mod-deployment-safety.md`](mod-deployment-safety.md) apply automatically to dev-promoted artifacts.
|
||
|
||
Escalation order:
|
||
|
||
1. File-level shadow rollback (`ROLLBACK_FILE`)
|
||
2. Snapshot restore (`ROLLBACK_SNAPSHOT`)
|
||
3. `FAILED_RECOVERY` — automation halts, state surfaced to UI
|
||
|
||
---
|
||
|
||
## 9. Restrictions (Phase 1)
|
||
|
||
- No automatic deployment on build completion
|
||
- No multiple game targets per Dev container
|
||
- No artifact version history or retention
|
||
- No dependency resolution
|
||
- No artifact diffing
|
||
- No background file watchers
|
||
|
||
**Manual promotion only.**
|
||
|
||
---
|
||
|
||
## 10. Security Requirements
|
||
|
||
| Requirement | Detail |
|
||
|-------------|--------|
|
||
| No auto-execution | Dev artifacts cannot execute automatically on placement |
|
||
| Ownership enforcement | API must validate same-owner constraint before any transfer |
|
||
| No direct writes | Dev container cannot write directly to Game container |
|
||
| SHA256 validation | Required on all artifact transfers |
|
||
| Size limits | Maximum artifact size enforced at API layer |
|
||
| File type restriction | Only `.jar` accepted; all other types rejected |
|
||
|
||
---
|
||
|
||
## 11. Observability Requirements
|
||
|
||
The Agent must emit structured log events for:
|
||
|
||
- Artifact promotion started
|
||
- Snapshot created
|
||
- Dev mod placed in `mods/dev/`
|
||
- Stabilization window started
|
||
- Auto-rollback triggered *(if applicable)*
|
||
- Deployment stabilized
|
||
- Recovery failed *(if applicable)*
|
||
|
||
The API must surface current deployment status to the frontend so the user can see promotion progress without polling manually.
|
||
|
||
---
|
||
|
||
## 12. Operational Guarantees
|
||
|
||
This pipeline guarantees:
|
||
|
||
- Dev experimentation cannot permanently brick a Game server
|
||
- Promotion is fully reversible via self-healing
|
||
- No SSH access required by the user at any point
|
||
- No manual file upload/download required
|
||
- All state changes are bounded and deterministic
|
||
|
||
---
|
||
|
||
## 13. Future Enhancements (Phase 2+)
|
||
|
||
- Multi-game promotion (one Dev → many Game targets)
|
||
- Artifact version history and retention
|
||
- Auto-deploy on successful build completion
|
||
- Promotion audit trail
|
||
- Dependency auto-detection
|
||
- CI webhook integration
|
||
|
||
---
|
||
|
||
## Final Decision Lock
|
||
|
||
| Decision | Value |
|
||
|----------|-------|
|
||
| Linking | Opt-in, explicit |
|
||
| Cardinality | One Dev → One Game (Phase 1) |
|
||
| Transfer orchestration | API-mediated, not container-direct |
|
||
| Safety enforcement | Agent-level, automatic |
|
||
| Mod channel separation | `mods/curated/` and `mods/dev/` are distinct |
|
||
| Snapshot + shadow protection | Applied on every promotion |
|
||
| Promotion trigger | Manual only (Phase 1) |
|