105 lines
4.2 KiB
Markdown
105 lines
4.2 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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.
|