141 lines
2.7 KiB
Markdown
141 lines
2.7 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.
|
||
|
||
---
|
||
|
||
## File System Capabilities (Current State)
|
||
|
||
### Read
|
||
- List
|
||
- Stat
|
||
- Read text files
|
||
- Download
|
||
- Hidden internal paths blocked (`.zlh_metadata.json`, `.zlh-shadow`)
|
||
|
||
### Write
|
||
- Full overwrite for:
|
||
- `server.properties`
|
||
- `config/*.toml`
|
||
- `config/*.json`
|
||
- `config/*.properties`
|
||
- Shadow backup created on first modification
|
||
- Manual revert supported
|
||
- No automated rollback for user writes
|
||
|
||
### 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 (raw `http.request` piping in API)
|
||
- Written atomically via `os.Rename()`
|
||
- 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` at runtime root.
|
||
|
||
```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:
|
||
|
||
```js
|
||
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 portal/API/agent alignment clean
|
||
|
||
---
|
||
|
||
## Update Instructions
|
||
|
||
When updating this repo:
|
||
|
||
1. Update `SESSION_LOG.md` with date-stamped entry
|
||
2. Update `OPEN_THREADS.md` if decisions were resolved
|
||
3. Update `CONSTRAINTS.md` if guardrails changed
|
||
4. Keep architecture docs consistent with real code behavior
|
||
5. Do not document future features as implemented
|
||
|
||
---
|
||
|
||
**System posture: Stable, controlled expansion phase.**
|