doc: elaborate high-level documentation (#192)

ARCHITECTURE.md

@@ -12,78 +12,226 @@ This document describes the high-level architecture of IronRDP.
 
 This section talks briefly about various important directories and data structures.
 
+Note also which crates are **API Boundaries**.
+Remember, [rules at the boundary are different](https://www.tedinski.com/2018/02/06/system-boundaries.html).
+
 ### Core Tier
 
 Set of foundational libraries for which strict quality standards must be observed.
+Note that all crates in this tier are **API Boundaries**.
 Pay attention to the "**Architecture Invariant**" sections.
 
-- `crates/ironrdp`: meta crate re-exporting important crates.
-- `crates/ironrdp-pdu`: PDU encoding and decoding. (TODO: talk about important types and traits such as PduDecode, PduEncode…)
-- `crates/ironrdp-graphics`: image processing primitives.
-- `crates/ironrdp-svc`: traits to implement RDP static virtual channels.
-- `crates/ironrdp-dvc`: DRDYNVC static channel implementation and traits to implement dynamic virtual channels.
-- `crates/ironrdp-rdpdr`: RDPDR channel implementation.
-- `crates/ironrdp-rdpsnd`: RDPSND static channel for audio output implemented as described in MS-RDPEA.
-- `crates/ironrdp-connector`: state machines to drive an RDP connection sequence.
-- `crates/ironrdp-session`: state machines to drive an RDP session.
-- `crates/ironrdp-input`: utilities to manage and build input packets.
-- `crates/ironrdp-rdcleanpath`: RDCleanPath PDU structure used by IronRDP web client and Devolutions Gateway.
-- `crates/ironrdp-error`: lightweight and `no_std`-compatible generic `Error` and `Report` types.
-  The `Error` type wraps a custom consumer-defined type for domain-specific details (such as `PduErrorKind`).
-
 **Architectural Invariant**: doing I/O is not allowed for these crates.
 
 **Architectural Invariant**: all these crates must be fuzzed.
 
-**Architectural Invariant**: no non-essential dependency is allowed.
-
 **Architectural Invariant**: must be `#[no_std]`-compatible (optionally using the `alloc` crate). Usage of the standard
 library must be opt-in through a feature flag called `std` that is enabled by default. When the `alloc` crate is optional,
 a feature flag called `alloc` must exist to enable its use.
 
+**Architectural Invariant**: no non-essential dependency is allowed.
+
+**Architectural Invariant**: no proc-macro dependency. Dependencies such as `syn` should be pushed
+as far as possible from the foundational crates so it doesn’t become too much of a compilation
+bottleneck. The paper [Developer Productivity For Humans, Part 4: Build Latency, Predictability,
+and Developer Productivity][developer-productivity] by Ciera Jaspan and Collin Green, Google
+researchers, elaborates on why it is important to keep build times low.
+
+**Architectural Invariant**: unless the performance, usability or ergonomic gain is really worth
+it, the amount of [monomorphization] incured in downstream user code should be minimal to avoid
+binary bloating and to keep the compilation as parallel as possible. Large generic functions should
+be avoided if possible.
+
+[developer-productivity]: https://www.computer.org/csdl/magazine/so/2023/04/10176199/1OAJyfknInm
+[monomorphization]: https://rustc-dev-guide.rust-lang.org/backend/monomorph.html
+
+#### [`crates/ironrdp`](./crates/ironrdp)
+
+Meta crate re-exporting important crates.
+
+**Architectural Invariant**: this crate re-exports other crates and does not provide anything else. 
+
+_TODO_: clean up the dependencies
+
+#### [`crates/ironrdp-pdu`](./crates/ironrdp-pdu)
+
+PDU encoding and decoding.
+
+_TODO_: talk about important types and traits such as PduDecode, PduEncode…
+
+#### [`crates/ironrdp-graphics`](./crates/ironrdp-graphics)
+
+Image processing primitives.
+
+_TODO_: break down into multiple smaller crates
+
+_TODO_: clean up the dependencies
+
+#### [`crates/ironrdp-svc`](./crates/ironrdp-svc)
+
+Traits to implement RDP static virtual channels.
+
+#### [`crates/ironrdp-dvc`](./crates/ironrdp-dvc)
+
+DRDYNVC static channel implementation and traits to implement dynamic virtual channels.
+
+#### [`crates/ironrdp-cliprdr`](./crates/ironrdp-cliprdr)
+
+CLIPRDR static channel for clipboard implemented as described in MS-RDPECLIP.
+
+#### [`crates/ironrdp-rdpdr`](./crates/ironrdp-rdpdr)
+
+RDPDR channel implementation.
+
+#### [`crates/ironrdp-rdpsnd`](./crates/ironrdp-rdpsnd)
+
+RDPSND static channel for audio output implemented as described in MS-RDPEA.
+
+#### [`crates/ironrdp-connector`](./crates/ironrdp-connector)
+
+State machines to drive an RDP connection sequence.
+
+#### [`crates/ironrdp-session`](./crates/ironrdp-session)
+
+State machines to drive an RDP session.
+
+#### [`crates/ironrdp-input`](./crates/ironrdp-input)
+
+Utilities to manage and build input packets.
+
+#### [`crates/ironrdp-rdcleanpath`](./crates/ironrdp-rdcleanpath)
+
+RDCleanPath PDU structure used by IronRDP web client and Devolutions Gateway.
+
+#### [`crates/ironrdp-error`](./crates/ironrdp-error)
+
+Lightweight and `no_std`-compatible generic `Error` and `Report` types.
+The `Error` type wraps a custom consumer-defined type for domain-specific details (such as `PduErrorKind`).
+
 ### Extra Tier
 
 Higher level libraries and binaries built on top of the core tier.
 Guidelines and constraints are relaxed to some extent.
 
-- `crates/ironrdp-blocking`: blocking I/O abstraction wrapping the state machines conveniently.
-- `crates/ironrdp-async`: provides `Future`s wrapping the state machines conveniently.
-- `crates/ironrdp-tokio`: `Framed*` traits implementation above `tokio`’s traits.
-- `crates/ironrdp-futures`: `Framed*` traits implementation above `futures`’s traits.
-- `crates/ironrdp-tls`: TLS boilerplate common with most IronRDP clients.
-- `crates/ironrdp-client`: portable RDP client without GPU acceleration using softbuffer and winit for windowing.
-- `crates/ironrdp-web`: WebAssembly high-level bindings targeting web browsers.
-- `web-client/iron-remote-gui`: core frontend UI used by `iron-svelte-client` as a Web Component.
-- `web-client/iron-svelte-client`: web-based frontend using `Svelte` and `Material` frameworks.
+#### [`crates/ironrdp-blocking`](./crates/ironrdp-blocking)
+
+Blocking I/O abstraction wrapping the state machines conveniently.
+
+This crate is an **API Boundary**.
+
+#### [`crates/ironrdp-async`](./crates/ironrdp-async)
+
+Provides `Future`s wrapping the state machines conveniently.
+
+This crate is an **API Boundary**.
+
+#### [`crates/ironrdp-tokio`](./crates/ironrdp-tokio)
+
+`Framed*` traits implementation above `tokio`’s traits.
+
+This crate is an **API Boundary**.
+
+#### [`crates/ironrdp-futures`](./crates/ironrdp-futures)
+
+`Framed*` traits implementation above `futures`’s traits.
+
+This crate is an **API Boundary**.
+
+#### [`crates/ironrdp-tls`](./crates/ironrdp-tls)
+
+TLS boilerplate common with most IronRDP clients.
+
+NOTE: it’s not yet clear if this crate is an API Boundary or an implementation detail for the native clients.
+
+#### [`crates/ironrdp-client`](./crates/ironrdp-client)
+
+Portable RDP client without GPU acceleration.
+
+#### [`crates/ironrdp-web`](./crates/ironrdp-web)
+
+WebAssembly high-level bindings targeting web browsers.
+
+This crate is an **API Boundary** (WASM module).
+
+#### [`web-client/iron-remote-gui`](./web-client/iron-remote-gui)
+
+Core frontend UI used by `iron-svelte-client` as a Web Component.
+
+This crate is an **API Boundary**.
+
+#### [`web-client/iron-svelte-client`](./web-client/iron-svelte-client)
+
+Web-based frontend using `Svelte` and `Material` frameworks.
 
 ### Internal Tier
 
 Crates that are only used inside the IronRDP project, not meant to be published.
 This is mostly test case generators, fuzzing oracles, build tools, and so on.
 
-- `crates/ironrdp-pdu-generators`: `proptest` generators for `ironrdp-pdu` types.
-- `crates/ironrdp-session-generators`: `proptest` generators for `ironrdp-session` types.
-- `crates/ironrdp-testsuite-core`: contains all integration tests for code living in the core tier, in a single binary,
-  organized in modules. **Architectural Invariant**: no dependency from another tier is allowed.
-  It must be the case that compiling and running the core test suite does not require building any library from
-  the extra tier. This is to keep iteration time short.
-- `crates/ironrdp-testsuite-extra`: contains all integration tests for code living in the extra tier, in a single binary,
-  organized in modules. (WIP: this crate does not exist yet.)
-- `crates/ironrdp-fuzzing`: provides test case generators and oracles for use with fuzzing.
-- `fuzz`: fuzz targets for code in core tier.
-- `xtask`: IronRDP’s free-form automation using Rust code.
-
 **Architecture Invariant**: these crates are not, and will never be, an **API Boundary**.
 
+#### [`crates/ironrdp-pdu-generators`](./crates/ironrdp-pdu-generators)
+
+`proptest` generators for `ironrdp-pdu` types.
+
+#### [`crates/ironrdp-session-generators`](./crates/ironrdp-session-generators)
+
+`proptest` generators for `ironrdp-session` types.
+
+#### [`crates/ironrdp-testsuite-core`](./crates/ironrdp-testsuite-core)
+
+Contains all integration tests for code living in the core tier, in a single binary, organized in modules.
+
+**Architectural Invariant**: no dependency from another tier is allowed. It must be the case that
+compiling and running the core test suite does not require building any library from the extra tier.
+This is to keep iteration time short.
+
+#### [`crates/ironrdp-testsuite-extra`](./crates/ironrdp-testsuite-extra)
+
+Contains all integration tests for code living in the extra tier, in a single binary, organized in modules.
+
+(WIP: this crate does not exist yet.)
+
+#### [`crates/ironrdp-fuzzing`](./crates/ironrdp-fuzzing)
+
+Provides test case generators and oracles for use with fuzzing.
+
+#### [`fuzz`](./fuzz)
+
+Fuzz targets for code in core tier.
+
+#### [`xtask`](./xtask)
+
+IronRDP’s free-form automation using Rust code.
+
 ### Community Tier
 
-Crates provided and maintained by the community.
-Core maintainers will not invest a lot of time into these.
-One or several community maintainers are associated to each one
+Crates provided and maintained by the community. Core maintainers will not invest a lot of time into
+these. One or several community maintainers are associated to each one.
+
+The IronRDP team is happy to accept new crates but may not necessarily commit to keeping them
+working when changing foundational libraries. We promise to notify you if such a crate breaks, and
+will always try to fix things when it's a minor change.
+
+#### [`crates/ironrdp-acceptor`](./crates/ironrdp-acceptor) (@mihneabuz)
+
+State machines to drive an RDP connection acceptance sequence
+
+#### [`crates/ironrdp-server`](./crates/ironrdp-server) (@mihneabuz)
+
+Extendable skeleton for implementing custom RDP servers.
+
+#### [`crates/ironrdp-glutin-renderer`](./crates/ironrdp-glutin-renderer) (no maintainer)
+
+`glutin` primitives for OpenGL rendering.
+
+#### [`crates/ironrdp-client-glutin`](./crates/ironrdp-client-glutin) (no maintainer)
+
+GPU-accelerated RDP client using glutin.
+
+#### [`crates/ironrdp-replay-client`](./crates/ironrdp-replay-client) (no maintainer)
 
-- `crates/ironrdp-glutin-renderer` (no maintainer): `glutin` primitives for OpenGL rendering.
-- `crates/ironrdp-client-glutin` (no maintainer): GPU-accelerated RDP client using glutin.
-- `crates/ironrdp-replay-client` (no maintainer): utility tool to replay RDP graphics pipeline for debugging purposes.
+Utility tool to replay RDP graphics pipeline for debugging purposes.
 
 ## Cross-Cutting Concerns
 

README.md

@@ -21,7 +21,7 @@ Supported codecs:
 
 A full-fledged RDP client based on IronRDP crates suite, and implemented using non-blocking, asynchronous I/O.
 
-```bash
+```shell
 cargo run --bin ironrdp-client -- <HOSTNAME> --username <USERNAME> --password <PASSWORD>
 ```
 
@@ -35,9 +35,9 @@ of code by leveraging the IronRDP crates suite.
 
 In this basic client implementation, the client establishes a connection
 with the destination server, decodes incoming graphics updates, and saves the
-resulting output as a BMP image file on the local disk.
+resulting output as a BMP image file on the disk.
 
-```bash
+```shell
 cargo run --example=screenshot -- --host <HOSTNAME> --username <USERNAME> --password <PASSWORD> --output out.bmp
 ```
 

crates/ironrdp-acceptor/Cargo.toml

@@ -2,7 +2,7 @@
 name = "ironrdp-acceptor"
 version = "0.1.0"
 readme = "README.md"
-description = ""
+description = "State machines to drive an RDP connection acceptance sequence"
 edition.workspace = true
 license.workspace = true
 homepage.workspace = true

crates/ironrdp-acceptor/README.md

@@ -1,3 +1,5 @@
 # IronRDP Acceptor
 
-State machine for the server connection acceptance sequence.
+State machines to drive an RDP connection acceptance sequence.
+
+For now, it requires the [Tokio runtime](https://tokio.rs/).

crates/ironrdp-blocking/README.md

@@ -3,5 +3,5 @@
 Blocking I/O abstraction wrapping the IronRDP state machines conveniently.
 
 This crate is a higher level abstraction for IronRDP state machines using blocking I/O instead of
-asynchronous I/O. This results in a simpler API with fewer dependencies that should be used
+asynchronous I/O. This results in a simpler API with fewer dependencies that may be used
 instead of `ironrdp-async` when concurrency is not a requirement.

crates/ironrdp-client/Cargo.toml

@@ -2,7 +2,7 @@
 name = "ironrdp-client"
 version = "0.1.0"
 readme = "README.md"
-description = "Portable RDP client without GPU acceleration using softbuffer and winit for windowing"
+description = "Portable RDP client without GPU acceleration"
 edition.workspace = true
 license.workspace = true
 homepage.workspace = true

crates/ironrdp-client/README.md

@@ -1,18 +1,22 @@
 # IronRDP client
 
-A full-fledged RDP client based on IronRDP crates suite, and implemented using non-blocking, asynchronous I/O.
+Portable RDP client without GPU acceleration.
+
+This is a a full-fledged RDP client based on IronRDP crates suite, and implemented using
+non-blocking, asynchronous I/O. Portability is achieved by using softbuffer for rendering
+and winit for windowing.
 
 ## Sample usage
 
-```bash
+```shell
 ironrdp-client <HOSTNAME> --username <USERNAME> --password <PASSWORD>
 ```
 
 ## Configuring log filter directives
 
 The `IRONRDP_LOG` environment variable is used to set the log filter directives. 
 
-```bash
+```shell
 IRONRDP_LOG="info,ironrdp_connector=trace" ironrdp-client <HOSTNAME> --username <USERNAME> --password <PASSWORD>
 ```
 
@@ -29,7 +33,7 @@ This file can be read by Wireshark so that in can decrypt the packets.
 
 ### Example
 
-```bash
+```shell
 SSLKEYLOGFILE=/tmp/tls-secrets ironrdp-client <HOSTNAME> --username <USERNAME> --password <PASSWORD>
 ```
 

crates/ironrdp-cliprdr/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "ironrdp-cliprdr"
 version = "0.1.0"
-description = "RDP PDU encoding and decoding"
 readme = "README.md"
+description = "CLIPRDR static channel for clipboard implemented as described in MS-RDPECLIP"
 edition.workspace = true
 license.workspace = true
 

crates/ironrdp-cliprdr/README.md

@@ -1,6 +1,8 @@
-# IronRDP clipboard library
+# IronRDP CLIPRDR
+
+CLIPRDR static channel for clipboard implemented as described in MS-RDPECLIP.
 
-Cliboard static virtual channel(SVC) implementation.
 This library includes:
-    - Cliboard SVC PDUs parsing
-    - Clipboard SVC processing (TODO)
+
+- CLIPRDR PDUs parsing
+- CLIPRDR processing (TODO)