catacomb/docs/superpowers/specs/2026-07-10-federation-editor-phase2-kind-aware-design.md

Kind-aware remote editor (phase 2)

Date: 2026-07-10 Status: Approved design, ready for implementation plan Scope: Desktop GUI + web server. Sub-project 2 of the PeerTube federation work.

Context

Phase 2 of three (see 2026-07-10-peertube-client-backend-design.md §Context). Phase 1 (backend PeerTubeClient + RemoteKind/username config) is done. This phase adds the in-UI editor to manage remotes of both kinds, applied live.

Inherits 2026-07-10-federation-remote-editor-design.md wholesale for the unchanged editor mechanics — read it first. Unchanged from that spec:

• WebState.remotes becomes a std::sync::RwLock<…>; browse endpoints read-lock, the editor save write-locks (live-apply).
• Dedicated /api/remotes/* endpoints (not folded into SettingsPayload): extended GET, new PUT (whole-list replace), new POST /api/remotes/test.
• Web passwords are masked / write-only; blank on save keeps the stored secret, matched by URL (merge_remote_passwords, pure + unit-tested). Desktop shows passwords in the clear (local).
• Config source of truth is state.config (state.config.lock_recover()); save via config.save; on save error, don't swap the live list; drop the config lock before taking the remotes lock.
• After any edit, both UIs refetch the list and clear the current selection.

This document specifies only the kind-aware deltas.

Delta 1 — Multi-kind live storage

New enum in src/remote.rs:

pub enum RemoteClientKind {
    Catacomb(RemoteClient),
    Peertube(crate::peertube::PeerTubeClient),
}

impl RemoteClientKind {
    pub fn from_section(cfg: &crate::config::RemoteSection) -> Self {
        match cfg.kind {
            crate::config::RemoteKind::Catacomb => Self::Catacomb(RemoteClient::new(cfg)),
            crate::config::RemoteKind::Peertube => Self::Peertube(crate::peertube::PeerTubeClient::new(cfg)),
        }
    }
    pub fn name(&self) -> &str {
        match self { Self::Catacomb(c) => &c.name, Self::Peertube(p) => &p.name }
    }
    pub fn kind(&self) -> crate::config::RemoteKind {
        match self {
            Self::Catacomb(_) => crate::config::RemoteKind::Catacomb,
            Self::Peertube(_) => crate::config::RemoteKind::Peertube,
        }
    }
}

• App.remotes: Vec<Arc<RemoteClientKind>> (desktop; mutable App, no lock).
• WebState.remotes: RwLock<Vec<Arc<RemoteClientKind>>> (web; per inherited spec). Built at startup with RemoteClientKind::from_section per config remote.
• Both fronts rebuild the whole Vec on editor save.

RemoteClient.name must be pub (it already is); PeerTubeClient.name is pub (phase 1).

Delta 2 — Browse dispatch (phase-2 stopgap)

The existing browse call-sites match on the enum:

• Web get_remote_library (positional :id): read-lock; match the entry:
  • Catacomb(c) → c.library_json() (unchanged behavior).
  • Peertube(_) → 501 Not Implemented / body "PeerTube browsing arrives in phase 3".
• Desktop start_remote_fetch(idx): match the entry:
  • Catacomb(c) → spawn the existing c.library() fetch (unchanged).
  • Peertube(_) → set remote_status = "PeerTube browsing arrives in a later update", no fetch.

So a PeerTube remote is fully manageable (add/edit/test/save) in phase 2; browsing it is phase 3. Catacomb browsing is untouched.

Delta 3 — Editor UI

The inherited "Federation peers" Settings section, each row gaining:

• a kind selector — Catacomb / PeerTube (egui::ComboBox desktop; <select> web);
• a username field, rendered only when kind = PeerTube;
• (unchanged) name, url, password (masked web / clear desktop), Test, Remove.

Desktop edits self.config.remotes (each RemoteSection now carries kind/username); on save rebuild self.remotes via from_section and reset remote_selected/remote_library. Web edits a JS array and saves via PUT.

Delta 4 — Web API

On top of the inherited endpoints:

• GET /api/remotes response gains kind (string, "catacomb"/"peertube"), keeps has_password — [{ id, name, url, kind, has_password }].
• PUT /api/remotes entry shape is { name, url, kind, username, password }. merge_remote_passwords (URL-keyed) unchanged; the rebuilt live list uses RemoteClientKind::from_section per merged RemoteSection.
• POST /api/remotes/test body { url, kind, username, password }. Build the matching client kind (resolving a blank password from the stored remote by URL, per the inherited merge) and check reachability on spawn_blocking:
  • catacomb → RemoteClient::library_json() ok → { ok: true } (optionally a channel count from the parsed library);
  • peertube → PeerTubeClient::list_channels() → { ok: true, channels: N };
  • failure → { ok: false, error }.

Delta 5 — Test-connection

Branches on kind as in Delta 4. Desktop runs it on a background thread (mirroring start_remote_fetch), delivering { ok, detail } over an mpsc channel drained in update(); the PeerTube arm calls list_channels().

Error handling

Inherited. Additionally: a PeerTube test against a bad instance/credentials fails at list_channels()/OAuth with a descriptive message; the remote can still be saved (peer may be down at edit time).

Testing

• Unit (remote.rs): RemoteClientKind::from_section builds the Catacomb variant for a default section and Peertube for kind = peertube; name()/kind() report correctly.
• Unit (inherited): merge_remote_passwords (URL-keyed keep-on-blank).
• Integration (tests/api.rs): PUT /api/remotes with one catacomb and one kind:"peertube" entry → GET /api/remotes reflects both with correct kind and has_password; a removed entry disappears; a blank-password edit of an existing entry keeps has_password true. (Live PeerTube reachability needs a real instance → manual.)
• Manual: in both UIs, add a catacomb peer and a public PeerTube remote (e.g. https://framatube.org/c/<channel>); Test each; save; confirm catacomb browse still works and clicking the PeerTube remote shows the phase-3 stopgap; confirm the web GET never returns plaintext passwords and blank-save preserves them.

What phase 3 consumes

The RemoteClientKind::Peertube arm's stopgap is replaced by the two-level lazy browse (list_channels → channel_videos) + inline play (video_media) + the per-video Archive action (watch_url → downloader).