tor-proto: Add a head comment explaining the conceptual division between tor-proto and higher layers
The tor-proto
crate should explain that tor-proto
is a function-only implementation of pieces of the Tor protocols: it does not understand what circuits and channels are getting used for, only how they should behave.
This distinction is important to avoid the antipattern where we get single flags (e.g. "This is an exit circuit") that have a complicated set of consequences (e.g. "Exit-ness influences the padding times, the queue timeouts, the cell scheduling priority, . All of those modules work by inspecting the exit-ness flag.") We're trying to prevent this antipattern by making it so the non-behavioral information is kept out of the code that implements the behavior.
So I should document that.