From e735692736163044c9d1d659516b1a85eccf026c Mon Sep 17 00:00:00 2001 From: Luna Date: Sun, 12 Jul 2026 02:09:07 -0700 Subject: [PATCH] docs: spec for PeerTube browse + archive (federation phase 3) Co-Authored-By: Claude Opus 4.8 --- ...26-07-12-peertube-browse-archive-design.md | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-12-peertube-browse-archive-design.md diff --git a/docs/superpowers/specs/2026-07-12-peertube-browse-archive-design.md b/docs/superpowers/specs/2026-07-12-peertube-browse-archive-design.md new file mode 100644 index 0000000..a98823f --- /dev/null +++ b/docs/superpowers/specs/2026-07-12-peertube-browse-archive-design.md @@ -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//`. 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, String>` — + `RemoteChannelInfo { handle, display_name, video_count: Option, avatar_url: Option }`. +- `channel_videos(handle, page) -> Result, 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, 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>` +(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, String>; + pub fn pt_channel_videos(&self, handle: &str, page: usize) -> Result, String>; + pub fn pt_video_media(&self, uuid: &str) -> Result, String>; + pub fn pt_watch_url(&self, uuid: &str) -> Result; +} +``` + +(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>`, + `pt_selected_channel: Option`, `pt_videos: Vec`, + `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//` 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).