Skip to content

File Browser Plan

Overview

A full-featured file browser for managing game server files. Built on the existing sidecar gRPC service, exposed through kernel HTTP endpoints, and rendered as a persistent multi-tab panel in the dashboard provision detail view.

Sidecar gRPC API (already implemented)

The sidecar exposes a FileIO gRPC service on port 4646. All operations are validated against VOLUME_PATH.

RPC Description
ListDirectory(Path) List directory entries with name, size, modified, isDirectory
ReadSmallFile(Path) Read file ≤ 3 MB, returns raw bytes
ReadFileStream(Path) Stream file in 4 MB chunks
WriteFileStream(stream FileChunk) Stream-write a file (path via gRPC metadata)
CreateFolder(Path) Create directory (recursive)
DeleteFile(Path) Delete single file
DeleteFolder(DeleteFolderReq) Delete folder, optionally recursive
MoveItem(MoveItemReq) Rename or move file/folder
CopyFile(CopyFileReq) Copy file or directory
ExtractFile(Path) Extract archive (auto-detects ZIP, 7z, tar.gz, tar.bz2, RAR)
CompressFiles(CompressFilesReq) Compress multiple files, configurable format
WatchDirectory(Path) Stream filesystem events (created/modified/deleted)

Kernel HTTP Endpoints

All routes under /api/v1/orders/{order_id}/provisions/{provision_id}/fs/. The provision_id refers to the primary game deployment provision — the kernel resolves the sidecar internally.

Permission Policy

All file browser endpoints require BrowseFiles order permission.

REST Endpoints

Method Path Description
GET /fs/list?path= List directory entries
GET /fs/read?path= Read file (small, ≤ 3 MB)
POST /fs/write Write text file { path, content }
POST /fs/mkdir Create directory { path }
POST /fs/move Move/rename { moves: [{from, to}] }
POST /fs/copy Copy { ops: [{from, to}] }
DELETE /fs/delete Delete { paths: [String], recursive: bool }
POST /fs/extract Extract archive { path }
POST /fs/compress Compress { sources: [String], output, format }

WebSocket Endpoints

Method Path Description
GET (WS) /fs/download?path= Stream file download (binary frames)
GET (WS) /fs/upload?path= Stream file upload (binary frames)
GET (WS) /fs/watch?path= Live filesystem events (JSON)

Error Responses

  • 403 — caller lacks BrowseFiles permission
  • 404 — order or provision not found
  • 400 — path traversal detected, invalid path, file too large
  • 502 — sidecar gRPC error

Dashboard Frontend

Architecture: Persistent Multi-Tab Panel

Tabs are never unmounted — they stay in the DOM and are only hidden/shown via CSS. This prevents losing editor state and scroll position when switching tabs.

FilesContent
├── TabBar — scrollable, middle-click to close
│   ├── FolderTab (default, "/ Home")
│   ├── EditorTab (per open file)
│   ├── MediaTab (per preview)
│   └── TerminalTab (singleton)
└── TabPanels (all rendered, only active shown)
    ├── FolderPanel
    ├── EditorPanel (Monaco)
    ├── MediaPanel
    └── TerminalPanel (reuses existing WS terminal)

Folder Panel Features

  • Dual view mode: list or grid, persisted in localStorage
  • Sorting: folders first, then alphabetical
  • Selection: click (single), Ctrl+click (toggle), Shift+click (range)
  • Keyboard shortcuts: Ctrl+C (copy), Ctrl+X (cut), Ctrl+V (paste), Delete, F2 (rename)
  • Drag-and-drop: onto folders, 15px activation threshold
  • Breadcrumb navigation: clickable path segments + back/forward buttons
  • Search: Ctrl+F to filter current directory (client-side)
  • Context menu: right-click → open, edit, preview, download, copy, cut, paste, rename, extract, compress, delete
  • Auto-refresh: on WatchDirectory events

Toolbar Actions

Action Condition Function
Home Always Open new folder tab at "/"
New File Folder tab active Prompt filename → create → open in editor
New Folder Folder tab active Prompt name → mkdir
Upload Folder tab active File picker or drag-drop → /fs/upload WS
Download 1 file selected /fs/download WS → browser SaveAs
Compress Items selected Modal: output filename + format
Extract Single archive selected POST /fs/extract
Rename Single item selected Inline rename input
Delete Items selected Confirm modal

Editor Panel

  • Monaco editor with syntax highlighting (dynamic import)
  • Files ≤ 3 MB: GET /fs/read → populate editor
  • Files > 3 MB: read-only view or streaming download prompt
  • Auto-save on change (500ms debounce) via POST /fs/write
  • Ctrl+S to save manually

Progress Tracking

Floating progress bar (bottom-right) shows active operations: - Upload/download: progress % + transfer speed - Compress/extract: spinner (indeterminate) - Multiple concurrent operations as a stacked list

Implementation Phases

Phase What
1 Kernel Infrastructure: SidecarPool, FileSystemService
2 Kernel HTTP REST Endpoints
3 Kernel HTTP WebSocket Endpoints (download, upload, watch)
4 Dashboard: FilesContent, FolderPanel, toolbar, EditorPanel, MediaPanel
5 Polish: keyboard shortcuts, context menu, auto-refresh, responsive layout