AGENTS.md

These instructions apply to the entire Frid workspace.

Project role

Frid is shared networking infrastructure. federation-net is the generic transport; music-dht is the distributed music-directory overlay used by Furumi applications. Treat public APIs, persisted state, hash derivations, and wire formats as compatibility-sensitive.

Read ARCHITECTURE.md before changing protocols, routing, persistence, rendezvous, tickets, identity, or record derivation.

Required checks

The workspace uses Rust edition 2024 and Rust 1.91 or newer.

cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

Integration tests open real sockets and establish iroh connections. If a restricted environment prevents socket binding or discovery, rerun them with the required permission and report the limitation; do not weaken or delete the tests.

Compatibility

Do not change these without an explicit migration/versioning decision:

ALPN byte strings;
transport, DHT, device-sync, catalog, or ticket versions;
NetworkId, SchemaId, NodeId, ItemId, or DhtKey derivation domains;
postcard/serde wire enum layouts;
content-ID normalization;
SQLite schema or identity-key encoding;
public re-exports from either crate.

Postcard is not self-describing. Adding a field to a serialized type can be a breaking wire change even when serde would accept the Rust source change.

Layer boundaries

federation-net owns identity, iroh endpoints, handshake, tickets, rendezvous, typed framing, event backpressure, and generic byte streams.
federation-net must not acquire music, catalog, playlist, or application authorization logic.
music-dht owns Kademlia routing, requests, records, replication, search, content lookup, and its persistence abstraction.
Rich catalogs, audio, and device sync use dedicated ALPN stream protocols; do not push bulk data through the typed DHT event channel.
Applications own policy: knowing a network ID or discovering a peer is not proof of authorization.

Async and concurrency

Never hold a mutex guard across .await.
Keep SQLite and blocking filesystem work off Tokio reactor threads.
Bound channels, request maps, batches, frames, and peer-provided collections.
Make shutdown idempotent and ensure background tasks cannot retain event senders indefinitely.
Preserve request peer-matching so a response from the wrong peer cannot resolve another peer's request.
Use dial backoff and bounded lookup work for dead contacts.

DHT behavior

Routing uses stable node IDs and XOR distance; do not replace derivation or ordering as a cosmetic refactor.
Validate that a record belongs under the key on which it was received.
Owners advance revisions; replicas do not rewrite ownership.
Tombstones must beat active records at the same or older revision.
TTL refresh, expiry, and republish behavior must remain deterministic.
sync_library is declarative and idempotent: unchanged items stay stable, changed items advance, and removed items are tombstoned.
Search may return partial results when peers fail, but lookup must terminate.

Tests

Add unit tests beside deterministic routing, framing, validation, storage, and merge logic. Use integration tests for behavior that depends on authenticated connections, handshakes, streams, disconnects, or multi-node lookup.

Tests must use temporary directories and isolated network/schema IDs. Never use a developer identity, repository tmp/ state, fixed public network, or real application database as a fixture.

For protocol changes, test both rejection of incompatible peers and the intended compatible path. For input-bound changes, test the limit and the first value beyond it.

Documentation and packaging

Keep crate-level rustdoc and README examples compiling.
Root documentation describes the workspace; crate READMEs describe their public API and operational model.
Do not describe Mainline-DHT rendezvous as private or as authorization.
Keep demo crates publish = false.
Published packages must include the WTFPL version 2 license text.
Update ARCHITECTURE.md when changing a protocol boundary or invariant.

4.2 KiB Raw Blame History