Advanced Rust: designing APIs that are hard to misuse

Syllabus

1. Names and documentation

   We will cover Rust's naming conventions as a compression scheme: what as_, to_, and into_ promise about cost and ownership, which words to borrow from the standard library, and which prefixes carry no information. You will also write doc comments for a caller who cannot see the body, including # Errors and # Panics sections and examples that cargo test keeps honest.

2. The newtype pattern

   You will give distinct things distinct types, so that a call to insert(bucket, key, value) cannot compile with its arguments in the wrong order. We will cover parsing rather than validating, so that a Key is evidence the check already ran, and encapsulation, including the doors that Deref, Default, and a derived Deserialize leave open.

3. Common traits

   A newtype starts with no traits at all, and most of them come back with one derive. We will cover the decisions derive cannot make for you: what Debug puts into your logs, the contract between Hash and Eq, Clone against Copy as a public commitment, and From and TryFrom as the generic entry points to the constructor you already wrote.

4. Ownership, borrowing, and lifetimes

   We will cover what & and &mut actually promise, lifetime elision and the anonymous lifetime, and the receiver as part of the API. You will work through aliasing against mutation from the inside, using retain and two-pass approaches, and remove the hidden clones from signatures that borrow what they then need to own.

5. RAII and drop guards

   You will add transactions to minidb, starting with a Transaction that borrows the store and cannot outlive it. We will cover drop guards that roll back automatically, drop bombs and why they have to check thread::panicking, the cases where Drop does not run at all, and a closure API that removes the possibility of forgetting to commit.

6. Typestate

   We will cover moving the state of a value into its type, so that the operations which are illegal in that state do not exist. You will build a read-only transaction with no insert method using marker types and PhantomData, then a document writer whose transitions consume self, which gives you a state machine with no runtime representation.

7. Extension traits

   We will cover the orphan rule and why you cannot add a method to str, then the extension trait pattern that works around it, including implementing for the unsized type and a blanket impl over another trait. We will also cover when to reach for a standard trait such as FromStr instead, and how method resolution decides which implementation a call reaches.

8. Polymorphism

   We will cover static and dynamic dispatch, dyn compatibility and the signatures it rules out, and how to keep a generic function thin so that monomorphisation does not duplicate its body once per type. You will also seal a trait, and we will cover when a closed set is better expressed as an enum.

9. PhantomData, variance, and brands

   We will cover what PhantomData does to size, auto traits, drop checking, and variance. You will give a handle that owns its data the borrowing behaviour of a reference, then use a branded lifetime and a higher-ranked bound so that keys built against one store cannot be used with another.