Files
frid/README.md
T
sanapachandClaude Opus 5.5 4f7e999280 Document podcast contract and bump crate versions
Add PODCASTS.md as the normative podcast contract: identity and URL
canonicalization, the no-GUID rule, synced versus local versus public
data, operation kinds and merge rules with examples, snapshot recovery,
version gating for peers below v4, Jam privacy and the reserved
playback_rate. Update PLAYBACK_PROTOCOL.md, ARCHITECTURE.md, the crate
READMEs and CHANGELOG.md.

Bump music-dht to 0.6.0 and furumi-library to 0.3.0: new public enum
variants and struct fields are breaking changes for 0.x, and
furumi-library re-exposes music-dht types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 15:40:55 +02:00

87 lines
3.4 KiB
Markdown

# frid
Frid is the shared infrastructure core behind Furumi. It provides reusable
Rust libraries for local music persistence and equal-peer networking without
an application server, central peer registry, or privileged node.
The workspace has three layers:
- [`federation-net`](crates/federation-net) establishes authenticated,
NAT-traversing P2P connections over iroh, isolates independent networks and
message schemas, and optionally discovers peers through the BitTorrent
Mainline DHT.
- [`music-dht`](crates/music-dht) builds a Kademlia-style distributed music
directory on top of that transport, including catalog discovery, content-id
lookup, signed similarity-LSH routing, direct byte streams, and shared Furumi
wire types, including the shared podcast contract ([PODCASTS.md](PODCASTS.md)).
- [`furumi-library`](crates/furumi-library) owns the shared local `library.db`
contract, migrations, catalog operations, metadata import, artwork,
playlists, likes, history, and similarity persistence used by Furumi clients.
Each participant is a client, router, and storage peer. Automatic rendezvous
has no Frid-operated bootstrap service, while self-contained peer tickets
remain available for explicit or isolated connections.
## Design principles
- **Equal peers.** No node receives a permanent coordinator or server role.
- **Application-owned protocols.** The transport moves typed messages and
byte streams without owning domain state.
- **Bounded inputs.** Frames, tickets, routing tables, requests, and record
batches have explicit limits.
- **Offline-tolerant discovery.** Records are replicated, refreshed by their
owners, expired by TTL, and removed through revisioned tombstones.
- **Protocol isolation.** Network IDs, schema IDs, versions, and ALPNs prevent
unrelated or incompatible applications from being merged accidentally.
- **Local persistence.** Identity, routing knowledge, owned records, and
replicas survive restarts in application-controlled storage.
See [ARCHITECTURE.md](ARCHITECTURE.md) for the protocol layers, trust model,
failure handling, and compatibility rules.
## Workspace
```text
crates/
federation-net/ generic iroh transport and rendezvous
music-dht/ distributed music catalog and content discovery
furumi-library/ client-independent local music database and import
```
## Using the libraries
Until crates are published to a registry, depend on the repository directly:
```toml
[dependencies]
federation-net = { git = "https://gt.hexor.cy/ab/frid.git" }
music-dht = { git = "https://gt.hexor.cy/ab/frid.git" }
furumi-library = { git = "https://gt.hexor.cy/ab/frid.git" }
```
Start with the crate documentation:
- [`federation-net` guide](crates/federation-net/README.md)
- [`music-dht` guide](crates/music-dht/README.md)
- [`furumi-library` guide](crates/furumi-library/README.md)
## Development
Frid uses Rust edition 2024 and requires Rust 1.97 or newer.
```bash
cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
```
The integration tests open real local sockets and establish iroh connections.
Some rendezvous tests also use public discovery infrastructure, so a restricted
sandbox may need explicit network permission.
## License
Frid is released under the
[Do What The Fuck You Want To Public License, Version 2](LICENSE).