2026-07-26 03:48:30 +03:00
|
|
|
# frid
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-08-11 18:07:19 +01:00
|
|
|
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.
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-08-11 18:07:19 +01:00
|
|
|
The workspace has three layers:
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
- [`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
|
2026-08-10 19:35:35 +01:00
|
|
|
lookup, signed similarity-LSH routing, direct byte streams, and shared Furumi
|
2026-11-19 15:40:55 +02:00
|
|
|
wire types, including the shared podcast contract ([PODCASTS.md](PODCASTS.md)).
|
2026-08-11 18:07:19 +01:00
|
|
|
- [`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.
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
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.
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
## Design principles
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
- **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.
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
See [ARCHITECTURE.md](ARCHITECTURE.md) for the protocol layers, trust model,
|
|
|
|
|
failure handling, and compatibility rules.
|
2026-07-10 12:45:47 +03:00
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
## Workspace
|
2026-07-10 12:45:47 +03:00
|
|
|
|
|
|
|
|
```text
|
2026-07-26 03:48:30 +03:00
|
|
|
crates/
|
|
|
|
|
federation-net/ generic iroh transport and rendezvous
|
|
|
|
|
music-dht/ distributed music catalog and content discovery
|
2026-08-11 18:07:19 +01:00
|
|
|
furumi-library/ client-independent local music database and import
|
2026-07-10 12:45:47 +03:00
|
|
|
```
|
|
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
## Using the libraries
|
|
|
|
|
|
2026-11-20 13:54:34 +00:00
|
|
|
Use the published crates from crates.io:
|
2026-07-26 03:48:30 +03:00
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[dependencies]
|
2026-11-20 13:54:34 +00:00
|
|
|
federation-net = "0.3.1"
|
|
|
|
|
music-dht = "0.6.0"
|
|
|
|
|
furumi-library = "0.3.0"
|
2026-07-26 03:48:30 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Start with the crate documentation:
|
|
|
|
|
|
|
|
|
|
- [`federation-net` guide](crates/federation-net/README.md)
|
|
|
|
|
- [`music-dht` guide](crates/music-dht/README.md)
|
2026-08-11 18:07:19 +01:00
|
|
|
- [`furumi-library` guide](crates/furumi-library/README.md)
|
2026-07-26 03:48:30 +03:00
|
|
|
|
|
|
|
|
## Development
|
|
|
|
|
|
2026-07-26 03:51:15 +03:00
|
|
|
Frid uses Rust edition 2024 and requires Rust 1.97 or newer.
|
2026-07-10 12:45:47 +03:00
|
|
|
|
|
|
|
|
```bash
|
2026-07-26 03:48:30 +03:00
|
|
|
cargo fmt --all -- --check
|
|
|
|
|
cargo check --workspace --all-targets --all-features
|
2026-07-10 12:45:47 +03:00
|
|
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
|
|
|
|
cargo test --workspace
|
|
|
|
|
```
|
|
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
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.
|
|
|
|
|
|
2026-11-20 13:54:34 +00:00
|
|
|
## Publishing
|
|
|
|
|
|
|
|
|
|
Add one repository Actions secret named `CARGO_REGISTRY_TOKEN`, containing a
|
|
|
|
|
crates.io API token with publish access to `federation-net`, `music-dht` and
|
|
|
|
|
`furumi-library`. No registry username or Gitea token secret is needed.
|
|
|
|
|
|
|
|
|
|
Update changed crate versions, workspace dependency requirements, `Cargo.lock`
|
|
|
|
|
and `CHANGELOG.md`, then merge to `main`. Create `<crate>-v<version>` tags for
|
|
|
|
|
the changed crates and one workspace release tag, for example:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git tag -a music-dht-v0.6.0 -m 'music-dht 0.6.0'
|
|
|
|
|
git tag -a furumi-library-v0.3.0 -m 'furumi-library 0.3.0'
|
|
|
|
|
git tag -a v0.6.0 -m 'Frid podcast release'
|
|
|
|
|
git push origin music-dht-v0.6.0 furumi-library-v0.3.0 v0.6.0
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Only the `v*` workspace tag triggers `.github/workflows/publish.yml`; the
|
|
|
|
|
crate tags identify each package release without starting duplicate uploads.
|
|
|
|
|
The workflow runs the workspace checks, selects every publishable workspace
|
|
|
|
|
crate whose exact version is absent from the crates.io sparse index, and lets
|
|
|
|
|
Cargo verify and publish the selected packages in dependency order. Versions
|
|
|
|
|
already published are skipped, so rerunning a partially completed release is
|
|
|
|
|
safe. A registry lookup error fails the release instead of assuming absence.
|
|
|
|
|
|
|
|
|
|
Preview the selection with `python3 scripts/publish_crates.py --plan`, or
|
|
|
|
|
verify the packages without uploading with `--dry-run`. If the secret was
|
|
|
|
|
missing or a publish failed, fix the cause and rerun the existing tag workflow;
|
|
|
|
|
do not move release tags. Manual dispatch must select the release tag as its
|
|
|
|
|
ref. Publication is performed by CI, not by the tagging commands above.
|
|
|
|
|
|
2026-07-26 03:48:30 +03:00
|
|
|
## License
|
|
|
|
|
|
|
|
|
|
Frid is released under the
|
|
|
|
|
[Do What The Fuck You Want To Public License, Version 2](LICENSE).
|