From 6112e83f62fa49195331aadedbe5fc8161e38af7 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Mon, 9 Nov 2026 00:10:19 +0000 Subject: [PATCH] Record Files panel upload behaviour, limits and verification --- app/notes/files-upload.md | 104 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 app/notes/files-upload.md diff --git a/app/notes/files-upload.md b/app/notes/files-upload.md new file mode 100644 index 00000000..676eb970 --- /dev/null +++ b/app/notes/files-upload.md @@ -0,0 +1,104 @@ +# Files panel: upload into the shown folder + +## Behaviour + +- The chat Files panel header has an **Upload files** button (next to Refresh). + It opens the host file picker (`hostChatAttachmentPicker`: `file_picker` on + native, `` on web). On a host without a picker the button is + disabled and its tooltip carries the reason + (`Upload files: `). +- The whole panel is a drop target. On web, `files_drop_web.dart` observes the + document's `dragenter`/`dragover`/`dragleave`/`drop` events through + `dart:js_interop`; a drag that carries files and sits over the panel is taken + over (default prevented, `dropEffect = copy`) and the panel shows a highlight + reading `Drop to upload to `. Drags elsewhere keep the browser's + default. Native hosts use `FilesDrop.unsupported` and keep the button only. +- Every picked or dropped file is posted on its own to + `POST /files?path=` (the listing's `path`), with the name in + `X-Pipelines-Upload-Name` (percent-encoded) and the MIME type as + `Content-Type`, through the same transport as chat uploads (`postChatUpload`: + session cookie on native, same-origin fetch on web; relay endpoints post to + `/peers//files`). After the batch the folder that received the files is + reloaded. +- Progress: `Uploading…` / `Uploading n of m…` with a progress strip; the + Upload button is disabled while a batch is in flight. +- Refusals are shown in the panel until dismissed (not swallowed), one line per + failed file; the rest of the batch is still attempted: + - 409: `"name" already exists in this folder.` (the server never overwrites) + - 401: `Sign in to upload files (Settings → Sign in).` + - 413: `"name" is too large to upload (100 MiB limit).` + - other statuses: the server's text, or `(HTTP n)` + - transport error / unreadable dropped item (a folder): reported in words. + +## Server and proxy + +- `internal/server/home_files_upload.go`: `POST /files?path=`. The folder + is resolved like `GET /files` (`expandHomePath` + `resolveInsideHome`, so it + must be inside `$HOME`, symlinks resolved); special filesystems and + non-directories are refused; the name must be a plain file name (no + separators, not `.`/`..`, ≤255 bytes); the file is created with `O_EXCL` and + mode 0644 (set explicitly, independent of umask), so an existing name is + `409 Conflict`; the chat upload limit (100 MiB) applies on `Content-Length` + and on the streamed body (partial file removed). Reply: + `{"name","path","size"}`. `GET /files` is unchanged. +- `web/serve.mjs` already forwarded every `/files` method to the server behind + the sign-in gate; `web/src/peerRelay.js` now allows `POST /files` beside + `POST /chat-uploads` (allowlist + POST check) and forwards + `content-type`, `content-length`, `x-pipelines-upload-name`. + +## Files + +- `app/lib/features/chat/files/files_upload.dart` — `postFileUpload` seam, + `uploadFileInto`, `FilesUploadException`. +- `files_drop.dart`, `files_drop_stub.dart`, `files_drop_web.dart` — drop seam. +- `files_drop_area.dart` — drop target with highlight. +- `files_upload_notice.dart` — progress and refusal strip (Material banner / + Cupertino message with Dismiss). +- `files_entries.dart` — the list/grid builders moved out of `files_panel.dart`. +- `files_controller.dart` — `upload`, `uploading`, `uploadTotal`, + `uploadError`, `reportUploadError`, `dismissUploadError`. +- `files_header.dart` — Upload button; `files_panel.dart` — `picker`/`drop` + parameters, drop wrap, notice. +- Tests: `app/test/features/chat/files/files_upload_test.dart`, + `files_panel_upload_test.dart`; `internal/server/home_files_upload_test.go`; + `web/test/serve.test.mjs`, `web/test/peerRelay.test.mjs`. + +## Verification (2026-11-09) + +``` +$ go test ./internal/server/ -run 'TestServeHomeFile|TestChatUpload' -v | grep -E "^(PASS|ok|FAIL)" +PASS +ok git.a-wan.net/alan/pipelines/internal/server 0.432s + +$ go test ./internal/server/... +ok git.a-wan.net/alan/pipelines/internal/server 65.194s + +$ cd web && node --test test/ +ℹ tests 16 +ℹ pass 16 +ℹ fail 0 + +$ cd app && tool/analyze.sh +analyze: clean; 7s; exit 0 + +$ cd app && tool/memwatch/full.sh test/features/chat/files +memwatch: PASS: 37 passed, 0 failed, 0 skipped; peak 1263 MB; 6s; exit 0 (test/features/chat/files) + +$ cd app && flutter build web --release +Compiling lib/main.dart for the Web... 25.0s +✓ Built build/web +``` + +## Not done / caveats + +- Desktop (macOS/Linux/Windows) drag-and-drop: not implemented. It would need + the `desktop_drop` plugin (a new native dependency in `pubspec.yaml`) whose + desktop builds could not be verified here; desktop hosts get the Upload + button, which works through `file_picker`. Mobile gets the button only, as + specified. +- No real-browser capture of the drag-and-drop interaction was recorded in this + lane (the web build compiles the interop; the drop path is covered through + the seam in widget tests). A browser drop requires a DataTransfer with files, + which the capture kit does not synthesise. +- The web drop listener assumes the Flutter view fills the page (it subtracts + the `flutter-view` element's bounding rect from the pointer position).