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:
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user