docs: update getting-started and contributing docs for v2

Remove the capnp compiler requirement from prerequisites (protobuf-src
vendors protoc automatically). Update building.md for 9 crates and the
justfile commands. Rewrite running-the-server.md with accurate v2 flags
(--allow-insecure-auth, --sealed-sender, --plugin-dir, --ws-listen,
--webtransport-listen, --federation-enabled, QPQ_PRODUCTION). Update
docker.md to remove capnproto install from builder stage description.
Delete bot-sdk.md and generators.md (removed crates). Update testing.md
with the accurate 301-test breakdown across 9 crates and the AUTH_LOCK
note for E2E tests. Update coding-standards.md dependency table to list
prost as primary serialisation, capnp as legacy-only, and add opaque-ke.
This commit is contained in:
2026-03-04 22:00:23 +01:00
parent 189534c511
commit f7a7f672b4
8 changed files with 405 additions and 675 deletions

View File

@@ -16,8 +16,7 @@ in any merged code:
- Stub implementations or placeholder logic
- Mock objects in production code paths (mocks are acceptable only in test code)
- Commented-out code blocks
- `#[allow(unused)]` on production code (acceptable on generated code from
Cap'n Proto codegen)
- `#[allow(unused)]` on production code (acceptable on prost-generated code)
If a feature is out of scope for the current milestone, it is **explicitly
omitted** with a documented reason (in an ADR or code comment explaining why it
@@ -84,11 +83,11 @@ pub fn create_group(
### Error Handling
- No `unwrap()` or `expect()` on cryptographic operations. All crypto errors
must be typed and propagated.
- No `unwrap()` or `expect()` on cryptographic operations or I/O in non-test
paths. All crypto errors must be typed and propagated.
- Use `thiserror` for library error types (`quicproquo-core`,
`quicproquo-proto`) and `anyhow` for application-level error handling
(`quicproquo-server`, `quicproquo-client`).
`quicproquo-proto`, `quicproquo-rpc`, `quicproquo-sdk`) and `anyhow` for
application-level error handling (`quicproquo-server`, `quicproquo-client`).
- `unwrap()` is acceptable only in:
- Test code.
- Cases where the invariant is provably guaranteed by the type system
@@ -119,6 +118,8 @@ pub fn create_group(
runtime stage.
- The Docker image must build and run correctly after every merge to the main
branch.
- The builder stage does not install extra system packages for code generation
`protobuf-src` vendors `protoc` automatically.
---
@@ -131,21 +132,27 @@ updates are allowed; major version bumps require justification and review.
### Preferred Ecosystem
| Domain | Preferred Crate(s) |
|--------|-------------------|
| Classical crypto (signing) | `ed25519-dalek` |
| Classical crypto (key exchange) | `x25519-dalek` |
| MLS | `openmls`, `openmls_rust_crypto` |
| Post-quantum KEM | `ml-kem` |
| Serialisation / RPC | `capnp`, `capnp-rpc` |
| Async runtime | `tokio` |
| Zeroisation | `zeroize` |
| Domain | Preferred Crate(s) | Notes |
|--------|-------------------|-------|
| Classical crypto (signing) | `ed25519-dalek` | |
| Classical crypto (key exchange) | `x25519-dalek` | |
| OPAQUE authentication | `opaque-ke` (v4) | Ristretto255 + Argon2 |
| MLS | `openmls 0.5`, `openmls_rust_crypto` | RFC 9420 |
| Post-quantum KEM | `ml-kem` (ML-KEM-768, FIPS 203) | |
| Serialisation / RPC (v2) | `prost`, `prost-build`, `protobuf-src` | Primary wire format |
| Serialisation (v1 legacy) | `capnp`, `capnp-rpc` | Legacy only, not for new code |
| Async runtime | `tokio` | |
| QUIC transport | `quinn` | |
| Middleware | `tower` | |
| Storage | `rusqlite` with `bundled-sqlcipher` | |
| Zeroisation | `zeroize` | |
| Internal serialisation | `bincode` | For MLS entities and file-backed store |
Do not introduce new dependencies without justification. In particular:
- No alternative async runtimes (async-std, smol).
- No alternative serialisation formats (protobuf, MessagePack, JSON) for wire
protocol use.
- No alternative serialisation formats for wire protocol use (new code must
use Protobuf via `prost`; Cap'n Proto is legacy-only).
- No alternative crypto libraries unless the preferred crate lacks required
functionality.
@@ -225,9 +232,9 @@ Background sweep is deferred to M6 (requires persistent storage).
### Linting
- `cargo clippy` with default lints. No `#[allow(clippy::...)]` without a
- `cargo clippy --workspace -- -D warnings`. No `#[allow(clippy::...)]` without a
comment explaining why the lint is suppressed.
- CI treats clippy warnings as errors.
- CI treats clippy warnings as errors (`-D warnings`).
### Naming
@@ -256,7 +263,7 @@ Before presenting any code for review, verify:
- [ ] No deviation from these standards.
- [ ] Doc comments on all public items.
- [ ] Tests for all new functionality (see [Testing Strategy](testing.md)).
- [ ] `cargo fmt`, `cargo clippy`, and `cargo test --workspace` all pass.
- [ ] `cargo fmt`, `cargo clippy --workspace -- -D warnings`, and `cargo test --workspace` all pass.
---