docs: add dev-to-game artifact promotion pipeline specification v1.0
This commit is contained in:
parent
c926cad4ff
commit
6d0c0d4c77
262
docs/architecture/dev-to-game-artifact-pipeline.md
Normal file
262
docs/architecture/dev-to-game-artifact-pipeline.md
Normal file
@ -0,0 +1,262 @@
|
|||||||
|
# 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) |
|
||||||
Loading…
Reference in New Issue
Block a user