Files
pipelines/app/notes/files-upload.md
T

105 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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, `<input type=file>` on web). On a host without a picker the button is
disabled and its tooltip carries the reason
(`Upload files: <unsupportedMessage>`).
- 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 <folder>`. 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=<shown folder>` (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/<id>/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=<dir>`. 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).