jester/zlh-grind
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
2c8a9de41c
zlh-grind/docs/architecture/filesystem-and-file-browser.md

5.4 KiB
Raw Blame History

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