docs: spec for PeerTube browse + archive (federation phase 3)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Luna
parent
b9271e4ab1
commit
e735692736
1 changed files with 186 additions and 0 deletions
|
|
@ -0,0 +1,186 @@
|
||||||
|
# PeerTube Browse + Archive — Design (Federation Phase 3)
|
||||||
|
|
||||||
|
> Third and final phase of the federation/PeerTube project. Phase 1 shipped the
|
||||||
|
> backend `PeerTubeClient` (`docs/superpowers/specs/2026-07-10-peertube-client-backend-design.md`);
|
||||||
|
> phase 2 shipped the kind-aware remote editor
|
||||||
|
> (`docs/superpowers/specs/2026-07-10-federation-editor-phase2-kind-aware-design.md`).
|
||||||
|
> This phase adds the browse UI + per-video archive action to both front-ends.
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Let a user browse a configured PeerTube peer's channels and videos from inside
|
||||||
|
Catacomb (both the web SPA and the desktop GUI), play a video inline when the
|
||||||
|
instance exposes a direct MP4, and archive any video into the local library with
|
||||||
|
one click. Read-only browsing, one-video-at-a-time archiving.
|
||||||
|
|
||||||
|
## Locked decisions (from brainstorming)
|
||||||
|
|
||||||
|
1. **Lazy two-level navigation** — list channels, then click a channel to load
|
||||||
|
its videos a page at a time. Not a one-shot whole-library load.
|
||||||
|
2. **Per-video archive only** — each video row has an Archive button. No
|
||||||
|
bulk/whole-channel archive in this phase.
|
||||||
|
3. **Archive destination = existing `Other` platform** — PeerTube is federated
|
||||||
|
with no fixed domain, so `Platform::from_url` classifies a `watch_url` as
|
||||||
|
`Other`, landing archived videos in `other/<uploader>/`. No new `Platform`
|
||||||
|
variant, no download-path override.
|
||||||
|
4. **Both front-ends in one spec** — web + desktop at parity, shared backend
|
||||||
|
endpoints.
|
||||||
|
5. **On-demand media resolution** — resolve a video's playable MP4 only when
|
||||||
|
Play is clicked, not eagerly for every listed video (eager would fire one
|
||||||
|
extra HTTP call per video per page).
|
||||||
|
|
||||||
|
## Background: what already exists
|
||||||
|
|
||||||
|
`PeerTubeClient` (phase 1, `src/peertube.rs`) is a blocking client with:
|
||||||
|
|
||||||
|
- `list_channels() -> Result<Vec<RemoteChannelInfo>, String>` —
|
||||||
|
`RemoteChannelInfo { handle, display_name, video_count: Option<u64>, avatar_url: Option<String> }`.
|
||||||
|
- `channel_videos(handle, page) -> Result<Vec<RemoteVideo>, String>` — page size
|
||||||
|
24, newest first. Returns `crate::remote::RemoteVideo { id (uuid), title,
|
||||||
|
channel, video_url: None, thumb_url, duration_secs }`. `video_url` is
|
||||||
|
deliberately `None` here — the playable URL is resolved separately.
|
||||||
|
- `video_media(uuid) -> Result<Option<String>, String>` — the direct MP4 URL, or
|
||||||
|
`None` when the video is HLS-only.
|
||||||
|
- `watch_url(uuid) -> String` — `{api_base}/w/{uuid}`, the canonical page URL
|
||||||
|
handed to yt-dlp.
|
||||||
|
|
||||||
|
`RemoteClientKind` (phase 2, `src/remote.rs`) wraps `Catacomb(RemoteClient)` /
|
||||||
|
`Peertube(PeerTubeClient)`. Both front-ends hold `Vec<Arc<RemoteClientKind>>`
|
||||||
|
(web behind a `RwLock`). Browsing dispatches on kind; the phase-2 stopgap for a
|
||||||
|
Peertube remote is a "browsing arrives in a later update" message, replaced here.
|
||||||
|
|
||||||
|
The existing **catacomb** browse path is untouched: `GET /api/remotes/:id/library`
|
||||||
|
returns the whole peer library and the SPA swaps its `library` array to reuse the
|
||||||
|
normal grid (`enterRemote`/`exitRemote` in `index.html`); desktop uses
|
||||||
|
`start_remote_fetch` → `remote_library`.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
Browsing remains **kind-dispatched**. Catacomb peers keep the one-shot `/library`
|
||||||
|
path. Peertube peers use new lazy endpoints and a new two-level browse view in
|
||||||
|
each UI. The new endpoints are Peertube-only: called against a catacomb remote
|
||||||
|
they return `400 Bad Request` ("not a PeerTube remote").
|
||||||
|
|
||||||
|
`RemoteClientKind` gains thin passthroughs used by the new web handlers and the
|
||||||
|
desktop threads:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
impl RemoteClientKind {
|
||||||
|
// Returns Err for the Catacomb arm ("not a PeerTube remote").
|
||||||
|
pub fn pt_channels(&self) -> Result<Vec<crate::peertube::RemoteChannelInfo>, String>;
|
||||||
|
pub fn pt_channel_videos(&self, handle: &str, page: usize) -> Result<Vec<RemoteVideo>, String>;
|
||||||
|
pub fn pt_video_media(&self, uuid: &str) -> Result<Option<String>, String>;
|
||||||
|
pub fn pt_watch_url(&self, uuid: &str) -> Result<String, String>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
(Alternatively the handlers `match` on the arm directly; the passthroughs keep the
|
||||||
|
`unreachable!()` noise out of both front-ends and give one kind-guard site.)
|
||||||
|
|
||||||
|
## Backend endpoints (`src/web.rs`)
|
||||||
|
|
||||||
|
All run the blocking PeerTube calls on `tokio::task::spawn_blocking` (as the
|
||||||
|
existing `get_remote_library` does) and 400 on a catacomb remote.
|
||||||
|
|
||||||
|
| Method / path | Returns |
|
||||||
|
|---|---|
|
||||||
|
| `GET /api/remotes/:id/channels` | `[{handle, display_name, video_count, avatar_url}]` |
|
||||||
|
| `GET /api/remotes/:id/channels/:handle/videos?page=N` | `[{id, title, channel, thumb_url, duration_secs}]` (page 24; `N` defaults 0) |
|
||||||
|
| `GET /api/remotes/:id/videos/:uuid/media` | `{url}` (200) or `204 No Content` when HLS-only |
|
||||||
|
| `POST /api/remotes/:id/archive` `{uuid}` | `202 "ok"` after `downloader.start(watch_url, …)`; 404 unknown remote, 400 catacomb remote |
|
||||||
|
|
||||||
|
`:handle` may contain `@host` for a federated channel, so it is a path segment
|
||||||
|
that is percent-decoded by axum; the handler passes it verbatim to
|
||||||
|
`channel_videos`. The archive handler resolves `watch_url(uuid)`, builds the
|
||||||
|
`UrlInfo` with the existing synchronous `classify_url(&url)` (no network probe;
|
||||||
|
`info.platform == Other` for a PeerTube URL), and calls the shared
|
||||||
|
`Downloader::start`. It mirrors `post_download`'s shape: `start` returns `()`,
|
||||||
|
so the response is `202 "ok"` and the job then appears in the normal downloads
|
||||||
|
panel via the existing progress stream (no job id is returned).
|
||||||
|
|
||||||
|
## Web UI (`src/web_ui/index.html`)
|
||||||
|
|
||||||
|
A new **PeerTube browse mode**, distinct from the existing flat-library
|
||||||
|
`remoteMode` (the PeerTube view is a two-level nav, not the reused grid):
|
||||||
|
|
||||||
|
- **Enter:** clicking a remote whose `kind === 'peertube'` in the sidebar enters
|
||||||
|
PeerTube mode and calls `GET …/channels`. (A catacomb remote still calls
|
||||||
|
`enterRemote`.) State: `ptRemoteId`, `ptChannel`, `ptPage`, `ptVideos`.
|
||||||
|
- **Channel list:** rows with avatar, display name, and video count. Click →
|
||||||
|
load that channel's videos.
|
||||||
|
- **Video grid:** cards (thumbnail, title, duration) with **▶ Play** and
|
||||||
|
**⬇ Archive**, plus a **[Load more]** button that fetches the next page and
|
||||||
|
appends (hidden when a page returns < 24).
|
||||||
|
- **Play:** `GET …/videos/:uuid/media`; on 200 open the existing custom player
|
||||||
|
(`playVideo`) with the returned URL; on 204 the Play button is disabled with an
|
||||||
|
"HLS-only — archive to watch" note.
|
||||||
|
- **Archive:** `POST …/archive {uuid}`; toast on success; the job shows up in the
|
||||||
|
normal downloads panel via the existing progress stream.
|
||||||
|
- **Back navigation:** video grid → channel list → "Back to my library"
|
||||||
|
(`exitRemote`-style reset). PeerTube mode reuses the sidebar remotes list for
|
||||||
|
peer switching.
|
||||||
|
|
||||||
|
Sidebar: the existing `🌐 Remotes` block already lists every peer with
|
||||||
|
`enterRemote(id)`. Dispatch there on `r.kind` — peertube → `enterPeertube(id)`.
|
||||||
|
|
||||||
|
## Desktop UI (`src/app.rs`)
|
||||||
|
|
||||||
|
`remotes_screen` dispatches on `RemoteClientKind::kind()`. The Peertube arm
|
||||||
|
replaces the phase-2 stopgap with the same two-level nav in egui:
|
||||||
|
|
||||||
|
- New `App` state: `pt_channels: Option<Vec<RemoteChannelInfo>>`,
|
||||||
|
`pt_selected_channel: Option<String>`, `pt_videos: Vec<RemoteVideo>`,
|
||||||
|
`pt_page: usize`, and mpsc receivers for the background channel/video fetches
|
||||||
|
(`pt_channels_rx`, `pt_videos_rx`) drained in `update()` — mirroring the
|
||||||
|
existing `remote_rx` pattern (fetch on a thread, `request_repaint`).
|
||||||
|
- Channel list (selectable rows) → click loads page 0 of that channel's videos;
|
||||||
|
a **Load more** button appends the next page.
|
||||||
|
- Per video row: **Play** — resolve `video_media` on a thread, then hand the URL
|
||||||
|
to the existing `play_remote_url` (mpv); greyed when the resolve returns `None`.
|
||||||
|
**Archive** — `self.downloader.start(watch_url, …)` (probe → `Other`).
|
||||||
|
- Status/errors surface on the existing `remote_status` line.
|
||||||
|
|
||||||
|
## Archive action (shared)
|
||||||
|
|
||||||
|
Both UIs route through the same `Downloader::start` a manual download uses, so
|
||||||
|
auto-retry, post-download transcode, and the hang watchdog all apply unchanged.
|
||||||
|
The archived video lands in `other/<uploader>/` and appears in the local library
|
||||||
|
after the next scan (the download pipeline already triggers this). No new
|
||||||
|
download settings, no per-remote archive options.
|
||||||
|
|
||||||
|
## HLS-only & error handling
|
||||||
|
|
||||||
|
- `video_media == None` (HLS-only): **Play disabled**, Archive still works
|
||||||
|
(yt-dlp downloads HLS fine). The disabled Play carries an explanatory tooltip.
|
||||||
|
- Network / auth / not-found failures from the PeerTube client surface as an
|
||||||
|
inline error line in the browse view (web: a status/toast; desktop:
|
||||||
|
`remote_status`) — never a panic or a stuck "loading…".
|
||||||
|
- An empty channel (zero videos) shows an empty-state row, not a blank grid.
|
||||||
|
- Calling a new endpoint on a catacomb remote → `400` with a clear message; the
|
||||||
|
UIs never do this (they dispatch on kind) but the guard documents intent and
|
||||||
|
protects the API.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- **Unit (web.rs):** the kind-guard — a new endpoint handler (or the
|
||||||
|
`RemoteClientKind` passthrough) returns `Err`/400 for a `Catacomb` arm. An
|
||||||
|
archive-path unit asserting a given `uuid` maps to the expected `watch_url`
|
||||||
|
before hand-off.
|
||||||
|
- **Integration (`tests/api.rs`):** `PUT` a peertube remote, then `GET
|
||||||
|
…/channels` against an unreachable host — asserts the route exists and returns
|
||||||
|
a client/gateway error (not 404-route-missing), and that `GET …/channels` on a
|
||||||
|
*catacomb* remote returns 400. No network required (unreachable host → fast
|
||||||
|
connection error); skip-if-curl-absent like the file's other tests.
|
||||||
|
- **Mapping:** already fixture-tested in phase 1 (`map_channel`, `map_video`,
|
||||||
|
`pick_media`) — no change.
|
||||||
|
- **Manual:** against `https://framatube.org` (public instance): browse
|
||||||
|
channels, open one, Load more, play a direct-MP4 video inline (web) / via mpv
|
||||||
|
(desktop), confirm an HLS-only video disables Play, archive one video and
|
||||||
|
confirm it lands under `Other` and appears after a rescan.
|
||||||
|
|
||||||
|
## Out of scope (possible later)
|
||||||
|
|
||||||
|
- Bulk / whole-channel archive.
|
||||||
|
- A dedicated `Platform::Peertube` library section.
|
||||||
|
- Search within a peer, subscriptions/feeds, comments, or write actions.
|
||||||
|
- Caching channel/video lists (each browse is a live fetch).
|
||||||
Loading…
Add table
Add a link
Reference in a new issue