diff --git a/crates/arti-client/README.md b/crates/arti-client/README.md index d046caaf6..70d61ba87 100644 --- a/crates/arti-client/README.md +++ b/crates/arti-client/README.md @@ -188,7 +188,7 @@ implementation with another. ### Experimental and unstable features Note that the APIs enabled by these features are NOT covered by semantic - versioning guarantees: we might break them or remove them between patch + versioning[^1] guarantees: we might break them or remove them between patch versions. * `experimental-api` -- build with experimental, unstable API support. @@ -199,4 +199,8 @@ implementation with another. * `experimental` -- Build with all experimental features above, along with all experimental features from other arti crates. +[^1]: Remember, semantic versioning is what makes various `cargo` features +work reliably. To be explicit: if you want `cargo update` to _only_ make safe +changes, then you cannot enable these features. + License: MIT OR Apache-2.0 diff --git a/crates/arti/README.md b/crates/arti/README.md index 4cb740fb3..2cd3f6dd2 100644 --- a/crates/arti/README.md +++ b/crates/arti/README.md @@ -54,6 +54,10 @@ example see [`arti_defaults.toml`](./arti_defaults.toml). (default) * `journald` -- Build with support for logging to the `journald` logging backend (available as part of systemd.) +* `dns-proxy` (default) -- Build with support for proxying certain simple + DNS queries over the Tor network. +* `harden` (default) -- Build with support for hardening the Arti process by + disabling debugger attachment and other local memory-inspection vectors. * `full` -- Build with all features above, along with all stable additive features from other arti crates. (This does not include experimental @@ -90,12 +94,19 @@ implementation with another. ### Experimental features Note that the APIs enabled by these features are NOT covered by semantic - versioning guarantees: we might break them or remove them between patch + versioning[^1] guarantees: we might break them or remove them between patch versions. +* `experimental-api` -- build with experimental, unstable API support. + (Right now, most APIs in the `arti` crate are experimental, since this + crate was originally written to run as a binary only.) * `experimental` -- Build with all experimental features above, along with all experimental features from other arti crates. +[^1]: Remember, semantic versioning is what makes various `cargo` features +work reliably. To be explicit, if you want `cargo update` to _only_ make +correct changes, then you cannot enable these features. + ## Limitations There are many missing features. Among them: there's no onion service diff --git a/crates/fs-mistrust/README.md b/crates/fs-mistrust/README.md index c08134d0c..187ce8bce 100644 --- a/crates/fs-mistrust/README.md +++ b/crates/fs-mistrust/README.md @@ -117,8 +117,9 @@ use fs_mistrust::Mistrust; let my_mistrust = Mistrust::builder() // Assume that our home directory and its parents are all well-configured. .ignore_prefix("/home/doze/") - // Assume that a given group will only contain trusted users. - .trust_group(413) + // Assume that a given group will only contain trusted users (this feature is only + // available on Unix-like platforms). + // .trust_group(413) .build()?; ``` diff --git a/crates/tor-congestion/README.md b/crates/tor-congestion/README.md index c09c488b5..f29d30e97 100644 --- a/crates/tor-congestion/README.md +++ b/crates/tor-congestion/README.md @@ -1 +1,15 @@ -(stub, will get replaced soon) +# tor-congestion + +`tor-congestion`: algorithms for congestion control on the Tor network + +## Overview + +This crate is part of +[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to +implement [Tor](https://www.torproject.org/) in Rust. + +This implements some of the algorithms needed to implement congestion control +as part of +[Tor proposal #324](https://gitlab.torproject.org/tpo/core/torspec/-/blob/main/proposals/324-rtt-congestion-control.txt). + +License: MIT OR Apache-2.0 diff --git a/crates/tor-proto/README.md b/crates/tor-proto/README.md index 3b62a1427..5b900985d 100644 --- a/crates/tor-proto/README.md +++ b/crates/tor-proto/README.md @@ -55,16 +55,32 @@ library, or the `arti` CLI. ## Design notes -This crate's APIs are structured to explicitly avoid any usage of -an asynchronous runtime: It doesn't launch tasks or include -timeouts. Those are done at a higher level in Arti, via the -[`tor-rtcompat`] crate. +This crate's APIs are structured to limit usage of an asynchronous runtime: +It doesn't launch tasks or create timers except when necessary. To the extent possible, this crate avoids doing public-key cryptography in the same functions it uses for network activity. This makes it easier for higher-level code to parallelize or yield around public-key operations. +Also, this crate tries to avoid knowing or encoding information about what +its objects (channels, circuits, streams) are "used for". That is, whenever +possible, we encode _how an object should behave_, not _the reason that it +should behave that way_. For example, the `Circuit` object in this crate +remembers the path through which the circuit was built, but _not_ the +purpose that the circuit serves, or what it may be used for. It's the +responsibility of other crates to enforce that kind of rule. + +Why separate behavior from purpose in this way? +We do so in order to prevent a kind of logical overloading that we ran into +with the C tor implementation, where usage information is _not_ separate +from behavioral settings. Since usage information is available, at all +points in the codebase the C tor code has converged in many places on +complex logic involving that usage information in order to set individual +behaviors. Because of that, adding a new kinds usage or behavior in C tor +has become quite complex. We're trying to avoid that kind of complexity in +Arti. + ## Limitations This is all a work in progress, and will need severe refactoring