199 lines
3.5 KiB
Markdown
199 lines
3.5 KiB
Markdown
# ZeroLagHub – Grind State Repository
|
||
|
||
This repository documents the current architecture, decisions, constraints, and open threads for ZeroLagHub (ZLH).
|
||
|
||
It is not a code repository.
|
||
It is the authoritative design + operational alignment layer between:
|
||
|
||
- Portal (Next.js frontend)
|
||
- API (Node + Express)
|
||
- Agent (Go runtime inside containers)
|
||
|
||
---
|
||
|
||
# Current System Overview
|
||
|
||
## Runtime Model
|
||
|
||
Each game container has a single runtime root:
|
||
|
||
/opt/zlh/minecraft/<runtime>/<world>/
|
||
|
||
All file operations are resolved relative to this root.
|
||
|
||
The agent is the only authority allowed to mutate the filesystem.
|
||
|
||
---
|
||
|
||
# Current Platform Capabilities (March 2026)
|
||
|
||
## Game Server Control
|
||
|
||
- Start / Stop / Restart
|
||
- Crash detection via process exit
|
||
- Intentional stop detection (no false crash increments)
|
||
- Readiness probing (Minecraft ping)
|
||
- Console streaming via WebSocket + PTY
|
||
- Crash metadata recorded by the agent
|
||
|
||
## File System Operations
|
||
|
||
- File browser
|
||
- Safe editing of server files
|
||
- Shadow backups (.zlh-shadow)
|
||
- Upload support:
|
||
- mods/*.jar
|
||
- world/datapacks/*.zip
|
||
- Upload provenance tracking via `.zlh_metadata.json`
|
||
|
||
## Observability
|
||
|
||
Agent `/status` endpoint exposes:
|
||
|
||
- `state`
|
||
- `crashCount`
|
||
- `lastCrashTime`
|
||
- `lastCrashExitCode`
|
||
- `lastCrashSignal`
|
||
- `lastCrashUptimeSeconds`
|
||
- `lastCrashLogTail`
|
||
|
||
## Notes System
|
||
|
||
Server instances support persistent notes stored in the platform database and editable from the portal UI.
|
||
|
||
## Console System
|
||
|
||
- xterm.js frontend
|
||
- WebSocket transport
|
||
- PTY session managed by the agent
|
||
- Reconnect handled client-side — no page refresh required
|
||
|
||
---
|
||
|
||
# File System Capabilities (Current State)
|
||
|
||
## Read
|
||
|
||
- List
|
||
- Stat
|
||
- Read text files
|
||
- Download
|
||
- Hidden internal paths blocked
|
||
|
||
## Write
|
||
|
||
- Full overwrite for:
|
||
- `server.properties`
|
||
- `config/*.toml`
|
||
- `config/*.json`
|
||
- `config/*.properties`
|
||
- Shadow backup created on first modification
|
||
- Manual revert supported
|
||
- No automated rollback
|
||
|
||
## Delete (Constrained)
|
||
|
||
Allowed only for:
|
||
|
||
- `mods-removed/<file>`
|
||
- `mods-uploaded/<file>`
|
||
- `logs/<file>.log`
|
||
- `logs/<file>.log.gz`
|
||
|
||
No directory deletes.
|
||
No recursive deletes.
|
||
|
||
## Upload
|
||
|
||
Allowed only for:
|
||
|
||
- `mods/<file>.jar`
|
||
- `world/datapacks/<file>.zip`
|
||
|
||
Uploads:
|
||
- Are streamed
|
||
- Written atomically
|
||
- Enforced by strict allowlist
|
||
- Do not create directories
|
||
- Do not use staging
|
||
- Do not use symlinks
|
||
|
||
---
|
||
|
||
# Provenance Model
|
||
|
||
User uploads write to:
|
||
|
||
.zlh_metadata.json
|
||
|
||
Example:
|
||
|
||
```json
|
||
{
|
||
"mods/sodium.jar": {
|
||
"source": "user",
|
||
"uploaded_at": "2026-03-01T22:37:01Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
stat returns:
|
||
|
||
`"source": "user" | null`
|
||
|
||
No curated inference currently implemented.
|
||
|
||
---
|
||
|
||
# Upload Transport
|
||
|
||
Browser → API → Agent
|
||
|
||
API uses raw Node http.request piping:
|
||
|
||
```
|
||
req.pipe(proxyReq)
|
||
proxyRes.pipe(res)
|
||
```
|
||
|
||
No fetch() streaming for uploads.
|
||
|
||
Upload timeout must be significantly larger than normal file operations.
|
||
|
||
---
|
||
|
||
# Console Model
|
||
|
||
TerminalView owns websocket lifecycle. ServerConsole owns policy + session gating.
|
||
|
||
Console reconnect is automatic. File panel does not interrupt console lifecycle.
|
||
|
||
---
|
||
|
||
# Repo Usage
|
||
|
||
This repo is used to:
|
||
|
||
- Prevent architecture drift
|
||
- Track decisions
|
||
- Record sessions
|
||
- Track open threads
|
||
- Keep frontend/API/agent alignment clean
|
||
|
||
---
|
||
|
||
# Update Instructions
|
||
|
||
When updating this repo:
|
||
|
||
1. Update SESSION_LOG with date-stamped entry.
|
||
2. Update OPEN_THREADS if decisions were resolved.
|
||
3. Update CONSTRAINTS if guardrails changed.
|
||
4. Keep architecture docs consistent with real code behavior.
|
||
5. Do not speculate future features as implemented.
|
||
|
||
---
|
||
|
||
System posture: Stable, controlled expansion phase.
|