docs: Files desk upload flow (approved for members and Minds), codes and caps as placeholders
Some checks failed
Build pull request / Build pull request (pull_request) Has been cancelled
Some checks failed
Build pull request / Build pull request (pull_request) Has been cancelled
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
88fd0a889a
commit
a8fc78ff55
1 changed files with 45 additions and 5 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Files desk: Commons and per-Persona file zones
|
||||
|
||||
Status: design only. No code, nothing deployed. Items marked **UNKNOWN** are not verified against the Body; **Q-E** / **Q-M** are open questions for Eureka (host) and Meta (audience, uploads), collected at the end.
|
||||
Status: design only. No code, nothing deployed. Items marked **UNKNOWN** are not verified against the Body; **Q-E** / **Q-M** are open questions for Eureka (host) and Meta (audience, names), collected at the end.
|
||||
|
||||
Source: Meta, #swarm 2026-11-13 14:28Z; ruling `ratatoskr:ruling:persona-file-sharing-zone` (each Persona has her own file sharing zone the frontend shows: a browsable, previewing collection; the Self writes to her outbox, her Persona decides what is shared, the Self never holds Matrix credentials).
|
||||
|
||||
|
|
@ -48,7 +48,7 @@ The host is a service on Yggdrasil that Eureka owns. The client holds no filesys
|
|||
- `path` is `<zone>/<relative path>`, with the zone one of the names the host announces. The host resolves the real path of every request and refuses anything that leaves the zone's root: `..`, absolute paths, NUL, symlinks that cross the root, dotfiles, and `handoff-private`, which is not on any allowlist. Errors are typed (`401 unauthenticated`, `403 zone not allowed`, `404`, `416`), and a path outside the allowlist is 404, not 403, so it says nothing about what exists.
|
||||
- **Auth: Matrix OpenID.** The client calls `mx.getOpenIdToken()` (already used in `CallWidgetDriver.ts`) and sends it as `Authorization: Bearer <token>`. The host verifies it against the homeserver's federation `openid/userinfo` endpoint, **pinned to our server name** (an `@void:evil.example` token must fail), caches the verified `sub` for the token's lifetime, and derives the role. It never sees the user's access token, and a Mind's Self never holds a token (ruling above): Minds reach the same bytes through the filesystem or the mouth, not this host.
|
||||
- **Role** in the response: `member`, `mind`, `steward` (host decides from the Matrix id and the room/space membership the host reads; the client trusts none of it for access). **Q-E:** exact source of membership (estate Space membership read by the host with a service account, versus the Persona catalogue file for Minds).
|
||||
- **Uploads, only if Meta approves (Q-M):** `PUT /file?path=<p>` with `Content-Length` required, a hard per-file cap (suggest 25 MiB; the existing Matrix limit is `m.upload.size` and the mouth fetches at most 5 MiB), no overwrite (409), into a single `inbox/` directory per zone, `201` with the stored name, size and hash, and the same path and sniff rules. Without approval the host serves no `PUT` and the client has no upload control; the `role` field is what would gate the control. The Matrix zone already carries uploads (`ShareSet`), so the Files desk does not need them to be useful.
|
||||
- **Uploads** (Meta approved for members and Minds, #swarm 2026-11-13 14:30Z; rules are Eureka's, below). `PUT /file?path=<p>` writes only under an `uploads/` subtree of a zone, with `Content-Length` required; the host enforces a size cap, a type allowlist (sniffed, not the client's claim), no overwrite unless the request carries an explicit flag, and never replaces a file a Mind wrote into the handoff tree; every write is audit-logged with the caller's Matrix id. Reads cover the whole allowlisted tree, so an uploaded file is listed like any other. Success is `201` with the stored name, size and hash. The `role` in the index response gates the upload control; the host gates the write.
|
||||
|
||||
### The one problem the contract leaves: media elements cannot send headers
|
||||
|
||||
|
|
@ -60,11 +60,47 @@ The host is a service on Yggdrasil that Eureka owns. The client holds no filesys
|
|||
|
||||
Recommendation: 2 for audio and video, 1 for images and text. Confidence moderate: I have not tested a service worker against range requests on the target phone, and 2 is the usual answer for authenticated media (signed URLs). **Q-E.**
|
||||
|
||||
## Upload flow
|
||||
|
||||
Design only. Every number and error code is a named placeholder until Eureka gives them on the PR: `<CAP_FILE>` (per-file size), `<CAP_BATCH>` (per-pick total, if any), `<TYPES>` (the allowlist), `<OVERWRITE_FLAG>` (the explicit query flag), and the codes `<E_AUTH>`, `<E_ROLE>`, `<E_PATH>`, `<E_TYPE>`, `<E_SIZE>`, `<E_EXISTS>`, `<E_PROTECTED>`, `<E_QUOTA>`, `<E_SERVER>`.
|
||||
|
||||
**Where.** The control exists only where an upload is allowed: inside a folder under a zone's `uploads/` subtree (or at the `uploads/` row itself), and only when the index `role` is member or mind. Elsewhere there is no button; the list does not carry a disabled one. A folder outside `uploads/` shows a one-line dim note, "Uploads go in uploads/", which links to that folder. Creating subfolders under `uploads/` is not in this design (**Q-E8**).
|
||||
|
||||
**Pick or drop.** One `Upload` row at the top of an `uploads/` folder opens the native picker (any number of files; on a phone this is the OS file sheet, camera roll included). On wide screens the list is also a drop target; the drop highlight appears only while a drag is over it. Nothing starts on pick: the picked files appear as a staging list (name, size, a type icon) with `Upload` and `Cancel` as full-width rows, as `ShareSet` does for a Matrix set. Files that already fail the client's cheap checks (over `<CAP_FILE>`, a type outside `<TYPES>`) are marked in the staging list with the reason and left out of the send; the client mirrors the cap and allowlist as a courtesy only, the host is the authority, and the list is read from the host (**Q-E9**: an `/index` field or a `/limits` call) rather than hard-coded.
|
||||
|
||||
**Send.** Files go one at a time, in pick order, each a `PUT /file?path=<folder>/<name>` with the bearer token. One at a time keeps a phone on mobile data from starving every transfer, and a refusal names exactly one file. The transport is `XMLHttpRequest`, not `fetch`: `fetch` has no upload progress and the row needs it. The body is the `File` itself (streamed by the browser, not read into memory; unlike the Matrix path, the client computes no hash first, the host returns one). The name is the file's own name, with path separators and control characters replaced, never a path the user typed.
|
||||
|
||||
**Progress.** The staging list becomes the progress list: per file a thin bar and "412 KB of 3.1 MB", per batch "2 of 5". Finished files show a tick and the stored name; refused ones show the refusal in place; waiting ones are dim. Only the active file animates. The list stays on screen after the last file until dismissed, so a refusal is not lost to a refresh of the folder underneath it. The folder listing refetches after each success, so the file appears in the list as it lands.
|
||||
|
||||
**Cancel.** `Cancel` on the active file aborts the request (`xhr.abort()`) and goes on to the next; `Cancel all` on the batch aborts the active file and drops the rest. The host must discard an aborted partial write and never leave a half file in the listing (**Q-E10**, written to a temporary name and renamed on completion). Leaving the page aborts whatever runs, as the Matrix share does; the client does not resume.
|
||||
|
||||
**Overwrite.** A name that already exists is refused with `<E_EXISTS>` and shown as "<name> is already there". A `Replace` row appears under that refusal only for a file the caller wrote themselves, and sends the same `PUT` with `<OVERWRITE_FLAG>`; a Mind-written handoff file refuses with `<E_PROTECTED>` and offers only "Keep both", which re-sends under a suffixed name (`name (2).ext`) chosen by the client. Whether the client can tell "mine" from the index (an `owner` field with the Matrix id) or learns it only from the refusal is **Q-E11**; absent an owner field, `Replace` is simply offered after `<E_EXISTS>` and the host's answer decides.
|
||||
|
||||
**Refusal messages.** One plain sentence per code, shown in the file's row; nothing says "error" without saying why, and none names a server path.
|
||||
|
||||
| Code | Message (draft) |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `<E_AUTH>` | Sign-in expired. Reload to upload again. (The client fetches a fresh OpenID token once and retries before showing this.) |
|
||||
| `<E_ROLE>` | Uploads are for members and Minds. |
|
||||
| `<E_PATH>` | That folder does not take uploads. |
|
||||
| `<E_TYPE>` | "<name>" is a <type> file; allowed types are <TYPES>. |
|
||||
| `<E_SIZE>` | "<name>" is <size>; the limit is <CAP_FILE>. |
|
||||
| `<E_EXISTS>` | "<name>" is already there. |
|
||||
| `<E_PROTECTED>` | "<name>" was written by a Mind and cannot be replaced. |
|
||||
| `<E_QUOTA>` | The shared space is full. Tell a steward. |
|
||||
| `<E_SERVER>` / network / timeout | Could not reach the file host. The file was not saved. |
|
||||
|
||||
Retry is one tap on a failed row; the batch never retries on its own. An unknown code shows the host's status text as it is, still without a path.
|
||||
|
||||
**Honest end state.** Done means the host answered `201` and the stored name, size and hash are shown. "Saved" is not said earlier; the hash the host returns is displayed so a sender can compare it with their own.
|
||||
|
||||
**Reuse and not.** `ShareSet`'s state machine (staging, one-send-per-zone guard, failed files kept by position) is the model, but the Matrix share path and its `createUploadAtom` are tied to the SDK's media upload and are not reused; the new controller sits in `features/files/uploadController.ts` with the same injected-port shape, so order, refusal and cancel rules are tested against a fake `PUT` without a browser. Real transfer progress and a real range of a phone's picker stay a phone check.
|
||||
|
||||
## Client shape
|
||||
|
||||
Under `src/app/features/files`, mirroring `features/albums`:
|
||||
|
||||
- `filesHost.ts`: ports, `list(path)`, `url(path)`, `ticket(path)`; the only module that knows the contract. Injected, so the UI is tested against a fake and the real client never runs in a test.
|
||||
- `filesHost.ts`: ports, `list(path)`, `url(path)`, `ticket(path)`, `put(path, file, onProgress, signal)`; the only module that knows the contract. Injected, so the UI is tested against a fake and the real client never runs in a test.
|
||||
- `useFilesZone.ts`: react-query on `['files', zone, path]`, `staleTime` 30 s; the role comes with every index.
|
||||
- `FilesDesk.tsx`, `FileRow.tsx`, `FilePreview.tsx`: pure rendering from the above; the preview picks its renderer from the host's `mime`, not the extension.
|
||||
- `config.json`: `filesDesk: { enabled: false, host: "https://…" }`, dark by default as `fileZoneShare.enabled` is. With it off, no row mounts and no request leaves the client.
|
||||
|
|
@ -76,7 +112,7 @@ Under `src/app/features/files`, mirroring `features/albums`:
|
|||
2. **Read-only Commons desk**: route, row, list, breadcrumb, role display, flagged off.
|
||||
3. **Preview and player**: image, audio with ranges, text, video; the ticket if Q-E settles on 2.
|
||||
4. **Per-Persona rows** in each Mind's group, once the outbox `shared/` convention and the zone provisioning exist.
|
||||
5. **Uploads**: only on Meta's yes.
|
||||
5. **Uploads**: the flow above; needs Eureka's codes and caps and the host's `PUT`.
|
||||
|
||||
Each is its own PR. Slices 1 to 3 need no host to build and test; slice 2 needs the real host to be useful, not to land.
|
||||
|
||||
|
|
@ -95,11 +131,15 @@ The Matrix file zone (marks, receipts, `ShareSet`); any Mind-side fetch (the mou
|
|||
- **Q-E5.** Per-Persona publishing: a `shared/` subdirectory versus a marker, and who populates it when the Persona decides.
|
||||
- **Q-E6.** Hash cost: compute lazily and cache by (path, mtime, size), or at publish time.
|
||||
- **Q-E7.** CORS for `chat.gamecult.org` and the dev previews, rate limits, and the `Content-Disposition` list.
|
||||
- **Q-E8.** Subfolders under `uploads/`: can a client create them (by a `PUT` path that implies them, or a `MKCOL`-like call), or is `uploads/` flat?
|
||||
- **Q-E9.** Cap and allowlist discovery: fields in the index response, or a `/limits` endpoint; and the exact codes and cap numbers behind every placeholder in the upload flow.
|
||||
- **Q-E10.** Partial writes: temporary name then rename, so an aborted or failed upload never appears in a listing.
|
||||
- **Q-E11.** Does the index carry an `owner` Matrix id per file (so `Replace` is offered only on one's own files), and is the audit log readable by stewards from the client or only on the host?
|
||||
|
||||
**For Meta:**
|
||||
|
||||
- **Q-M1.** Audience: Commons for members and Minds as proposed; are Users and Patrons ever in (the Matrix zone's audience question, `ratatoskr:question:file-zone-audience`, is the same fork)?
|
||||
- **Q-M2.** Is a Persona's zone visible to all members or to her stewards and Minds?
|
||||
- **Q-M3.** Uploads: yes or no, and if yes, who (members, Minds, stewards) and the cap.
|
||||
- **Q-M3.** ~~Uploads~~ approved for members and Minds (2026-11-13 14:30Z); open only: may Users or Patrons upload if they are ever let in?
|
||||
- **Q-M4.** Name: "Files" for the row, "Commons" for the shared zone.
|
||||
- **Q-M5.** Does the Matrix Media row stay beside the Files row on each Mind, or does one absorb the other once the Files desk exists (recommendation: both stay; marks and receipts are Matrix's).
|
||||
|
|
|
|||
Loading…
Reference in a new issue