Introduce 'Idiomatic Rust' learning module (#2800)

This PR introduces:

- A new section for the "Idiomatic Rust" learning module
- (The beginning of) the section on newtype patterns

---------

Co-authored-by: Dmitri Gribenko <[email protected]>

Author: LukeMathWalker

mdbook-course/src/replacements.rs

@@ -48,7 +48,8 @@ pub fn replace(
                 ["course", "outline"] if course.is_some() => {
                     course.unwrap().schedule()
                 }
-                ["course", "outline", course_name] => {
+                ["course", "outline", course_name @ ..] => {
+                    let course_name = course_name.join(" ");
                     let Some(course) = courses.find_course(course_name) else {
                         return format!("not found - {}", captures[0].to_string());
                     };

src/SUMMARY.md

@@ -429,6 +429,17 @@
 
 ---
 
+# Idiomatic Rust
+
+- [Welcome](idiomatic/welcome.md)
+- [Leveraging the Type System](idiomatic/leveraging-the-type-system.md)
+  - [Newtype Pattern](idiomatic/leveraging-the-type-system/newtype-pattern.md)
+    - [Semantic Confusion](idiomatic/leveraging-the-type-system/newtype-pattern/semantic-confusion.md)
+    - [Parse, Don't Validate](idiomatic/leveraging-the-type-system/newtype-pattern/parse-don-t-validate.md)
+    - [Is It Encapsulated?](idiomatic/leveraging-the-type-system/newtype-pattern/is-it-encapsulated.md)
+
+---
+
 # Final Words
 
 - [Thanks!](thanks.md)

src/idiomatic/leveraging-the-type-system.md

@@ -0,0 +1,53 @@
+---
+minutes: 5
+---
+
+# Leveraging the Type System
+
+Rust's type system is _expressive_: you can use types and traits to build
+abstractions that make your code harder to misuse.
+
+In some cases, you can go as far as enforcing correctness at _compile-time_,
+with no runtime overhead.
+
+Types and traits can model concepts and constraints from your business domain.
+With careful design, you can improve the clarity and maintainability of the
+entire codebase.
+
+<details>
+
+Additional items speaker may mention:
+
+- Rust's type system borrows a lot of ideas from functional programming
+  languages.
+
+  For example, Rust's enums are known as "algebraic data types" in languages
+  like Haskell and OCaml. You can take inspiration from learning material geared
+  towards functional languages when looking for guidance on how to design with
+  types. ["Domain Modeling Made Functional"][1] is a great resource on the
+  topic, with examples written in F#.
+
+- Despite Rust's functional roots, not all functional design patterns can be
+  easily translated to Rust.
+
+  For example, you must have a solid grasp on a broad selection of advanced
+  topics to design APIs that leverage higher-order functions and higher-kinded
+  types in Rust.
+
+  Evaluate, on a case-by-case basis, whether a more imperative approach may be
+  easier to implement. Consider using in-place mutation, relying on Rust's
+  borrow-checker and type system to control what can be mutated, and where.
+
+- The same caution should be applied to object-oriented design patterns. Rust
+  doesn't support inheritance, and object decomposition should take into account
+  the constraints introduced by the borrow checker.
+
+- Mention that type-level programming can be often used to create "zero-cost
+  abstractions", although the label can be misleading: the impact on compile
+  times and code complexity may be significant.
+
+</details>
+
+{{%segment outline}}
+
+[1]: https://pragprog.com/titles/swdddf/domain-modeling-made-functional/

src/idiomatic/leveraging-the-type-system/newtype-pattern.md

@@ -0,0 +1,51 @@
+---
+minutes: 5
+---
+
+# Newtype Pattern
+
+A _newtype_ is a wrapper around an existing type, often a primitive:
+
+```rust
+/// A unique user identifier, implemented as a newtype around `u64`.
+pub struct UserId(u64);
+```
+
+Unlike type aliases, newtypes aren't interchangeable with the wrapped type:
+
+```rust,compile_fail
+# pub struct UserId(u64);
+fn double(n: u64) -> u64 {
+    n * 2
+}
+
+double(UserId(1)); // 🛠️❌
+```
+
+The Rust compiler won't let you use methods or operators defined on the
+underlying type either:
+
+```rust,compile_fail
+# pub struct UserId(u64);
+assert_ne!(UserId(1), UserId(2)); // 🛠️❌
+```
+
+<details>
+
+- Students should have encountered the newtype pattern in the "Fundamentals"
+  course, when they learned about
+  [tuple structs](../../user-defined-types/tuple-structs.md).
+
+- Run the example to show students the error message from the compiler.
+
+- Modify the example to use a typealias instead of a newtype, such as
+  `type MessageId = u64`. The modified example should compile, thus highlighting
+  the differences between the two approaches.
+
+- Stress that newtypes, out of the box, have no behaviour attached to them. You
+  need to be intentional about which methods and operators you are willing to
+  forward from the underlying type. In our `UserId` example, it is reasonable to
+  allow comparisons between `UserId`s, but it wouldn't make sense to allow
+  arithmetic operations like addition or subtraction.
+
+</details>

src/idiomatic/leveraging-the-type-system/newtype-pattern/is-it-encapsulated.md

@@ -0,0 +1,54 @@
+---
+minutes: 5
+---
+
+# Is It Truly Encapsulated?
+
+You must evaluate _the entire API surface_ exposed by a newtype to determine if
+invariants are indeed bullet-proof. It is crucial to consider all possible
+interactions, including trait implementations, that may allow users to bypass
+validation checks.
+
+```rust
+pub struct Username(String);
+
+impl Username {
+    pub fn new(username: String) -> Result<Self, InvalidUsername> {
+        // Validation checks...
+        Ok(Self(username))
+    }
+}
+
+impl std::ops::DerefMut for Username { // ‼️
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}
+# impl std::ops::Deref for Username {
+#     type Target = str;
+#
+#     fn deref(&self) -> &Self::Target {
+#         &self.0
+#     }
+# }
+# pub struct InvalidUsername;
+```
+
+<details>
+
+- `DerefMut` allows users to get a mutable reference to the wrapped value.
+
+  The mutable reference can be used to modify the underlying data in ways that
+  may violate the invariants enforced by `Username::new`!
+
+- When auditing the API surface of a newtype, you can narrow down the review
+  scope to methods and traits that provide mutable access to the underlying
+  data.
+
+- Remind students of privacy boundaries.
+
+  In particular, functions and methods defined in the same module of the newtype
+  can access its underlying data directly. If possible, move the newtype
+  definition to its own separate module to reduce the scope of the audit.
+
+</details>

src/idiomatic/leveraging-the-type-system/newtype-pattern/parse-don-t-validate.md

@@ -0,0 +1,58 @@
+---
+minutes: 5
+---
+
+# Parse, Don't Validate
+
+The newtype pattern can be leveraged to enforce _invariants_.
+
+```rust
+pub struct Username(String);
+
+impl Username {
+    pub fn new(username: String) -> Result<Self, InvalidUsername> {
+        if username.is_empty() {
+            return Err(InvalidUsername::CannotBeEmpty)
+        }
+        if username.len() > 32 {
+            return Err(InvalidUsername::TooLong { len: username.len() })
+        }
+        // Other validation checks...
+        Ok(Self(username))
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+# pub enum InvalidUsername {
+#     CannotBeEmpty,
+#     TooLong { len: usize },
+# }
+```
+
+<details>
+
+- The newtype pattern, combined with Rust's module and visibility system, can be
+  used to _guarantee_ that instances of a given type satisfy a set of
+  invariants.
+
+  In the example above, the raw `String` stored inside the `Username` struct
+  can't be accessed directly from other modules or crates, since it's not marked
+  as `pub` or `pub(in ...)`. Consumers of the `Username` type are forced to use
+  the `new` method to create instances. In turn, `new` performs validation, thus
+  ensuring that all instances of `Username` satisfy those checks.
+
+- The `as_str` method allows consumers to access the raw string representation
+  (e.g., to store it in a database). However, consumers can't modify the
+  underlying value since `&str`, the returned type, restricts them to read-only
+  access.
+
+- Type-level invariants have second-order benefits.
+
+  The input is validated once, at the boundary, and the rest of the program can
+  rely on the invariants being upheld. We can avoid redundant validation and
+  "defensive programming" checks throughout the program, reducing noise and
+  improving performance.
+
+</details>

src/idiomatic/leveraging-the-type-system/newtype-pattern/semantic-confusion.md

@@ -0,0 +1,73 @@
+---
+minutes: 5
+---
+
+# Semantic Confusion
+
+When a function takes multiple arguments of the same type, call sites are
+unclear:
+
+```rust
+# struct LoginError;
+pub fn login(username: &str, password: &str) -> Result<(), LoginError> {
+    // [...]
+    # Ok(())
+}
+
+# let password = "password";
+# let username = "username";
+// In another part of the codebase, we swap arguments by mistake.
+// Bug (best case), security vulnerability (worst case)
+login(password, username);
+```
+
+The newtype pattern can prevent this class of errors at compile time:
+
+```rust,compile_fail
+pub struct Username(String);
+pub struct Password(String);
+# struct LoginError;
+
+pub fn login(username: &Username, password: &Password) -> Result<(), LoginError> {
+    // [...]
+    # Ok(())
+}
+
+# let password = Password("password".into());
+# let username = Username("username".into());
+login(password, username); // 🛠️❌
+```
+
+<details>
+
+- Run both examples to show students the successful compilation for the original
+  example, and the compiler error returned by the modified example.
+
+- Stress the _semantic_ angle. The newtype pattern should be leveraged to use
+  distinct types for distinct concepts, thus ruling out this class of errors
+  entirely.
+
+- Nonetheless, note that there are legitimate scenarios where a function may
+  take multiple arguments of the same type. In those scenarios, if correctness
+  is of paramount importance, consider using a struct with named fields as
+  input:
+  ```rust
+  pub struct LoginArguments<'a> {
+      pub username: &'a str,
+      pub password: &'a str,
+  }
+  # fn login(i: LoginArguments) {}
+  # let password = "password";
+  # let username = "username";
+
+  // No need to check the definition of the `login` function to spot the issue.
+  login(LoginArguments {
+      username: password,
+      password: username,
+  })
+  ```
+  Users are forced, at the callsite, to assign values to each field, thus
+  increasing the likelihood of spotting bugs.
+  <!-- TODO: Link to the relevant section in "Foundations of API design" when that chapter is written -->
+
+</details>