docs: add filesystem and file browser architecture planning doc
This commit is contained in:
parent
991047bf92
commit
b1003ddb9e
142
docs/architecture/filesystem-and-file-browser.md
Normal file
142
docs/architecture/filesystem-and-file-browser.md
Normal file
@ -0,0 +1,142 @@
|
||||
# ZeroLagHub – File System & File Browser Strategy
|
||||
|
||||
**Date:** 2026-02-28
|
||||
**Status:** Planning — not yet implemented
|
||||
**Next Action:** Stub file endpoints in existing agent, prove end-to-end, extract later
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
This document captures the architectural decisions and UX direction for file system access in ZeroLagHub game and dev containers. It is a planning document, not an implementation spec.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Game Server Owners (non-technical)
|
||||
- Edit `server.properties` and config files
|
||||
- Upload mod `.jar` files to `/mods`
|
||||
- Restore deleted mods from `/mods-removed`
|
||||
- Download log files for debugging
|
||||
|
||||
### Developers / BYOS (technical)
|
||||
- Full shell access
|
||||
- File transfer (upload/download)
|
||||
- SFTP access to dev container filesystem
|
||||
|
||||
These are two distinct personas with different needs and different solutions.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Decision
|
||||
|
||||
### Game Server File Access
|
||||
Handled via **agent file endpoints + portal file browser UI**.
|
||||
|
||||
No SSH required. The agent exposes REST file management endpoints. The API proxies them behind auth + ownership enforcement (same pattern as all other agent endpoints). The portal renders a file browser panel.
|
||||
|
||||
### Dev Container File Access
|
||||
Handled via **WebSSH2 + SFTP**, proxied through the API.
|
||||
|
||||
Developers get a real SSH2 session with SFTP channel. No direct container access from the browser — API proxy maintains the security boundary (DEC-008).
|
||||
|
||||
---
|
||||
|
||||
## Agent File Endpoints (Planned)
|
||||
|
||||
```
|
||||
GET /game/files?path= — list directory
|
||||
GET /game/files/download?path= — download file
|
||||
POST /game/files/upload?path= — upload file
|
||||
DELETE /game/files?path= — delete file
|
||||
PATCH /game/files — rename file
|
||||
```
|
||||
|
||||
Mirrored in API under:
|
||||
```
|
||||
/api/game/servers/:id/files/*
|
||||
```
|
||||
|
||||
### Security Requirements
|
||||
- Hard-rooted to `serverRoot` — no path traversal outside container root
|
||||
- HTTPS only
|
||||
- Auth + ownership enforced at API layer
|
||||
- Upload size limits enforced
|
||||
- No execution of uploaded files
|
||||
|
||||
---
|
||||
|
||||
## Implementation Sequencing
|
||||
|
||||
**Do not split the agent yet.**
|
||||
|
||||
Land file endpoints in the existing agent first. Prove the feature end-to-end. Once the surface area is clear and stable, extract if needed.
|
||||
|
||||
SFTP is the exception — if SFTP access for dev containers is implemented, it warrants its own separate process from day one due to SSH server complexity. It does not belong in the main game agent.
|
||||
|
||||
### Phased approach
|
||||
1. File endpoints in existing agent (stub → prove → harden)
|
||||
2. Portal file browser UI wired to API proxy
|
||||
3. SFTP as separate agent process for dev containers (separate binary, separate port, separate systemd unit)
|
||||
|
||||
---
|
||||
|
||||
## Frontend File Browser Direction
|
||||
|
||||
### Layout
|
||||
Split-pane panel — directory tree left, file detail/actions right. Slides in as a panel, does not replace the console view. Server console remains visible.
|
||||
|
||||
### Navigation
|
||||
Breadcrumb-based. Flat navigation within each directory rather than deep tree expansion. Click folder → replace view. Not expand-in-place.
|
||||
|
||||
### File Listing
|
||||
Columns: name, size, modified date, type icon. For `.jar` files: status badge (enabled / disabled / removed).
|
||||
|
||||
### Actions
|
||||
Context menu or per-row three-dot menu. Actions: download, delete, rename. For `.jar` files: enable / disable toggle. Drag-to-upload supported, file picker fallback.
|
||||
|
||||
### In-Browser Editor
|
||||
Plain textarea or Monaco for text files (`server.properties`, `.json`, `.txt`). Binary files get download link only. Not required for launch.
|
||||
|
||||
### `mods-removed` Surface
|
||||
"Recently removed" section or toggle to show `/mods-removed` alongside active mods. This makes soft delete visible and gives users a restore path without knowing the underlying filesystem layout.
|
||||
|
||||
### What to Avoid
|
||||
- Deep expand/collapse tree for mod directory (use flat list + filter)
|
||||
- In-browser zip/unzip
|
||||
- Making the file browser the primary surface — mod manager stays primary, file browser is secondary/advanced
|
||||
|
||||
---
|
||||
|
||||
## Per-Container Web Server Decision
|
||||
|
||||
**Do not run Nginx or Caddy per container.**
|
||||
|
||||
The agent already runs an HTTP server. Serving static file browser assets from the agent directly keeps per-container footprint minimal. No additional process, no config management, no extra memory overhead.
|
||||
|
||||
Caddy or Nginx per container would make sense if you needed per-container SSL termination or direct browser access without the API proxy. ZLH's architecture routes everything through the API proxy (`zlh-proxy` handles SSL at the edge), so a local web server adds a layer without adding capability.
|
||||
|
||||
---
|
||||
|
||||
## Resilience Notes
|
||||
|
||||
The file agent (when extracted) should follow the same binary resilience pattern as the main agent:
|
||||
|
||||
- Versioned release layout (`releases/<version>/`)
|
||||
- `current` symlink pointing to active binary
|
||||
- Previous version retained on disk
|
||||
- Systemd watchdog flips `current` back to previous on health check failure
|
||||
- No dependency on artifact server for rollback — local fallback only
|
||||
|
||||
This keeps the file service self-healing without operator intervention, consistent with ZLH's overall design goal.
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `docs/architecture/mod-deployment-safety.md` — mod lifecycle and rollback model
|
||||
- `docs/architecture/dev-to-game-artifact-pipeline.md` — dev container promotion pipeline
|
||||
- `OPEN_THREADS.md` — file browser listed as next major feature
|
||||
- `Frontend/TerminalView_Component.md` (knowledge-base) — terminal implementation reference
|
||||
- WebSSH2: `https://github.com/billchurch/webssh2` — SFTP + SSH2 for dev containers
|
||||
Loading…
Reference in New Issue
Block a user