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