devsyncwrld/backspace
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

docs(api,federation): tus upload endpoints; federation worker boundary note

Browse Source
This commit is contained in:
Jannis Braun
2026-05-02 17:16:00 +02:00
parent fb7add4f83
commit 38a3d4fba8
2 changed files with 18 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/systems/api.md
+14 -2
View File
@@ -184,9 +184,21 @@ PATCH /spaces/:id/join-requests/:rid { action } → { request } [M
GET /users/@me/join-requests ?status= → { requests[] }
```
## Uploads (`routes/uploads.ts`)
## Uploads (`routes/files.ts`, `routes/uploads.ts`)
### Tus Upload Endpoints
| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| POST | `/api/files/` | JWT | Create resumable upload. Returns `Location` (upload URL) and `Upload-Expires`. |
| HEAD | `/api/files/:uploadId` | JWT (ownership) | Probe `Upload-Offset` for resume. |
| PATCH | `/api/files/:uploadId` | JWT (ownership) | Append bytes at offset. |
| DELETE | `/api/files/:uploadId` | JWT (ownership) | Abort. |
The final PATCH that completes an upload returns the `Attachment` JSON in its response body. See `docs/systems/uploads.md` for the full pipeline (PRE_CREATE / PRE_PATCH / POST_FINISH hooks, storage layout, janitor).
### File Serving
```
POST /uploads (auth, multipart, rate-limited) → { attachment }
GET /uploads/:filename (public, supports Range) → file stream
```
docs/systems/federation.md
+4
View File
@@ -898,6 +898,10 @@ When the origin instance receives a `file_rejected` event:
Uses the same backoff schedule as outbox delivery. Max attempts: 10 (`MAX_FILE_ATTEMPTS`). After exceeding max attempts: `status = 'failed'`, `rejectionReason = 'max_attempts_exceeded'`.
### Boundary vs. tus Upload Migration (2026-04)
The `federation_file_queue` worker downloads files from peer instances via plain `fetch` + `Readable.fromWeb` to disk, post-completion. It consumes finished files at `${uploadDir}/${filename}`. Whether a file got there via the legacy multipart endpoint, the current tus endpoint at `/api/files/*`, or any future protocol is invisible to this worker -- its contract is purely with the on-disk filename. No changes were required when the upload protocol changed.
---
## 8. Read State Relay