lanspread/crates/lanspread-peer/README.md

# lanspread-peer

`lanspread-peer` is the networking runtime that lets Lanspread nodes find each
other on the local network, exchange library metadata, and transfer game files.
It is designed to run headless – other crates (most notably
`lanspread-tauri-deno-ts`) embed it and drive it through a channel-based API.

## Runtime Overview

- `start_peer(game_dir, tx_events, peer_game_db, unpacker, catalog)` boots the
  asynchronous runtime in the background and returns a `PeerRuntimeHandle` whose
  sender controls the peer. The injected `Unpacker` keeps archive extraction out
  of the peer crate's platform layer, and the catalog set gates which local game
  roots are announced or served.
- `PeerCommand` represents the small control surface exposed to the UI layer:
  `ListGames`, `GetGame`, `FetchLatestFromPeers`, `DownloadGameFiles`,
  `StreamInstallGame`, `InstallGame`, `UninstallGame`, `RemoveDownloadedGame`,
  `CancelDownload`, `SetGameDir`, and `GetPeerCount`.
- `PeerEvent` enumerates everything the peer runtime reports back to the UI:
  library snapshots, download/install/uninstall lifecycle updates, runtime
  failures, and peer membership changes.
- `PeerGameDB` collects remote peer metadata. It aggregates discovered peers’
  `Game` definitions, tracks the latest ETI version per title, and keeps the
  last seen list of `GameFileDescription` entries for each peer.

Internally the peer runtime owns four long-lived tasks that run for the lifetime
of the process:

1. **Server component** (`run_server_component`) – listens for QUIC connections,
   advertises via mDNS, and serves `Request::ListGames`, `Request::GetGame`,
   `Request::GetGameFileData`, `Request::GetGameFileChunk`, and
   `Request::StreamInstall` by reading from the local game directory.
2. **Discovery loop** (`run_peer_discovery`) – uses the `lanspread-mdns` helper
   to discover other peers. The blocking mDNS work is executed on a dedicated
   thread via `tokio::task::spawn_blocking` so that the Tokio runtime remains
   responsive.
3. **Ping service** (`run_ping_service`) – periodically issues QUIC ping
   requests to keep peer liveness up to date and prunes stale entries from
   `PeerGameDB`.
4. **Local game monitor** (`run_local_game_monitor`) – watches the configured
   game directory and each game root non-recursively, gates per-ID rescans while
   operations are active, emits local-library changes separately from active
   operation snapshots, and runs a 300-second fallback scan for missed events.

`scan_local_library` maintains a lightweight on-disk index and produces both a
`GameDB` and protocol summaries. A game is downloaded only when its root-level
`version.ini` sentinel exists; `local/` being a directory is the install signal.

## Networking and File Transfer

- Transport is handled by [`s2n-quic`](https://github.com/aws/s2n-quic); TLS
  cert/key material is compiled in from the repository root.
- Protocol messages are JSON-encoded structures defined in
  `lanspread-proto::{Request, Response}`.
- File transfers stream raw bytes over dedicated bidirectional QUIC streams.
  `peer::send_game_file_data` sends entire files, while
  `peer::send_game_file_chunk` services ranged requests.

### Download Pipeline

When the UI asks to download a game:

1. The UI first issues `PeerCommand::GetGame` for a new download, or
   `PeerCommand::FetchLatestFromPeers` for an update that must bypass local
   archives. The selected peers are queried via
   `request_game_details_from_peer`, and their file manifests are merged inside
   `PeerGameDB`.
2. Once the UI receives `PeerEvent::GotGameFiles`, it requests the download by
   game ID only. The peer core validates every source manifest before consensus,
   chooses the complete authoritative description, and constructs one
   root-confined `ValidatedDownloadManifest` before any filesystem mutation.
3. `download_game_files` recovers any earlier attempt, parks an old
   `version.ini` as `.version.ini.discarded`, and durably journals the exact old
   and proposed downloader-owned file sets before preparing non-sentinel files.
   It then emits `PeerEvent::DownloadGameFilesBegin` and builds a per-peer plan
   (`build_peer_plans`) that round-robins file chunks across the available peers
   that advertise the latest version.
4. Each plan is executed in its own task (`download_from_peer`). Chunk requests
   use per-chunk QUIC streams and write into pre-created files. The chunk writer
   keeps existing data intact and only truncates when we intentionally fall back
   to a full file transfer, which prevents corruption when multiple peers fill
   different regions of the same file.
5. `DownloadProgressTracker` samples byte counters, transfer speed, and the
   number of unique peers that are actively streaming chunks. The Tauri UI sees
   those values together through the regular download-progress event.
6. `version.ini` chunks are buffered in memory. After transfer, paths owned by
   the previous successful download but absent from the new manifest are
   removed. Payload files and their directories are synced before the new
   sentinel is committed last via `.version.ini.tmp` followed by an atomic
   rename. A sentinel rename whose directory sync fails leaves ownership pending
   for recovery instead of being reported as a durable success. Transfer
   failures are accumulated and retried (up to `MAX_RETRY_COUNT`) via
   `retry_failed_chunks`.
7. Failure, cancellation, and startup recovery use the journal to remove only
   exact downloader-owned files. Unknown user files, `local/`, and install
   transaction state are preserved. A regular `version.ini` beside a pending
   journal proves that the final rename landed; otherwise recovery aborts the
   incomplete payload.
8. After a successful sentinel commit, `PeerEvent::DownloadGameFilesFinished` is
   emitted and the peer auto-runs the install transaction.

### Streamed Install Pipeline

Low-disk installs use `PeerCommand::StreamInstallGame` instead of the normal
archive download pipeline. The peer core owns the whole operation: it refreshes
file metadata from catalog-version peers, runs the same majority file-size
validation used by normal downloads, selects a validated peer list, and emits
the regular download/install lifecycle events while streaming archive-expanded
bytes directly into a `StreamedInstallTransaction`.

The sender-side `StreamInstallProvider` writes control and chunk frames through
a cancellable `StreamInstallFrameSink`. If the QUIC writer fails because the
receiver cancelled or disconnected, the sink wakes any producer blocked on the
bounded frame channel and lets the transfer guard drop normally.

Each failed peer attempt rolls back its staging directory before trying the next
validated peer. A transaction that created a previously missing game root
removes that root again when rollback leaves it empty. Once staging has been
renamed to `local/`, post-promote intent or launch-settings cleanup failures are
logged for startup recovery rather than reported as a failed install.

`PeerCommand::CancelDownload` cancels the tracked download token for an active
transfer. The transfer task remains responsible for clearing
`active_operations`, discarding partial payload files, and refreshing the
settled local snapshot, so the UI continues to treat active-operation snapshots
as the single source of truth for whether a download is still running.

### Install Transactions

Install, update, uninstall, downloaded-file removal, and startup recovery live
under `src/install/`. Install-side operation intent is stored atomically under
the configured peer state directory, at `games/<game_id>/install_intent.json`.
Game roots still use Lanspread-owned `.local.installing/` and `.local.backup/`
directories marked by `.lanspread_owned`. Startup recovery combines the recorded
intent with the observed filesystem state and only deletes reserved directories
when intent or marker ownership proves they belong to Lanspread. Downloaded-file
removal is deliberately separate from uninstall: it only accepts catalog IDs
that are direct children of the configured game directory, refuses installed or
in-flight roots, and deletes the whole game root only after finding a regular
root-level `version.ini` sentinel.

Download provenance is stored separately at
`games/<game_id>/download_ownership.json` in the peer state directory. It is
bound to the canonical configured games directory so switching library roots
cannot make an old record authorize deletion in a different tree.

Legacy launcher-owned files in game directories are migrated by a dedicated
pre-start phase. Normal install, recovery, scan, and transfer paths use only the
configured state directory for launcher-owned metadata.

## Integration with `lanspread-tauri-deno-ts`

The Tauri application embeds this crate in
`crates/lanspread-tauri-deno-ts/src-tauri/src/lib.rs`:

- `LanSpreadState` holds onto the peer control channel, the latest aggregated
  `GameDB`, per-game operation state, the catalog set, and the user-selected
  game directory.
- The Tauri commands (`request_games`, `install_game`, `update_game`,
  `remove_downloaded_game`, and `update_game_directory`) translate UI actions
  into `PeerCommand`s. In particular, `update_game_directory` validates the
  filesystem path before storing it, loads the bundled catalog on first use,
  kicks off the peer runtime on demand, and mirrors the installed/uninstalled
  state into the UI-facing database.
- A background task consumes `PeerEvent`s and fans them out to the front-end via
  Tauri publish/subscribe events (`games-list-updated`, `game-download-*`,
  `game-install-*`, `game-uninstall-*`, `peer-*`). The Tauri crate now only
  provides the unrar sidecar through the injected `Unpacker`; rollback and
  cleanup live in the peer transaction code.

## Security & Operational Notes

- All QUIC connections are TLS encrypted; the shipped certificates are suitable
  for local-network trust but should be rotated for production deployments.
- Peer discovery is restricted to the local link via mDNS.
- Long-running blocking mDNS calls are isolated on dedicated threads which keeps
  the async runtime responsive even when discovery takes a long time.
- File writes are chunk-safe: partial chunk downloads open files without
  truncating existing data, and root-level `version.ini` is written only after
  the rest of the download has succeeded.

## Known Limitations

- `PeerGameDB` currently models the latest metadata that other peers advertise.
  If the UI needs to surface titles that only exist locally, additional merging
  with the locally scanned `GameDB` will be required.
- The download planner uses a simple round-robin and does not yet take per-peer
  throughput or failures into account when distributing work.

Refer to the source (particularly `src/lib.rs`) for the exact message shapes and
state machines.