177 lines
9.8 KiB
Markdown
177 lines
9.8 KiB
Markdown
# 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 forwards the selected file
|
||
list back with `PeerCommand::DownloadGameFiles`.
|
||
3. `download_game_files` starts a version-sentinel transaction, parks any old
|
||
`version.ini` as `.version.ini.discarded`, prepares non-sentinel files, 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 and committed last via
|
||
`.version.ini.tmp` followed by an atomic rename. Failures are accumulated and
|
||
retried (up to `MAX_RETRY_COUNT`) via `retry_failed_chunks`; failed downloads
|
||
sweep `.version.ini.tmp` and `.version.ini.discarded` without restoring the
|
||
previous sentinel. Cancelled downloads also discard the peer-owned download
|
||
payload while preserving `local/` and install transaction metadata.
|
||
7. 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.
|
||
|
||
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.
|