@booklib/core 2.0.0

package/skills/rust-in-action/examples/after.md

@@ -0,0 +1,156 @@
+# After: Rust in Action
+
+The same utility rewritten with idiomatic systems Rust — explicit endianness, buffered I/O, a domain error type, checksum validation, thread pool, and safe shared state.
+
+```rust
+use std::fmt;
+use std::fs::File;
+use std::io::{BufReader, Read};
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+use std::sync::mpsc;
+use std::thread;
+
+// Domain error type — wraps all downstream errors (Ch 3, 8)
+#[derive(Debug)]
+pub enum LogError {
+    Io(std::io::Error),
+    InvalidRecord { offset: usize, reason: &'static str },
+    ChecksumMismatch { expected: u32, got: u32 },
+}
+
+impl fmt::Display for LogError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            LogError::Io(e) => write!(f, "I/O: {e}"),
+            LogError::InvalidRecord { offset, reason } =>
+                write!(f, "invalid record at {offset}: {reason}"),
+            LogError::ChecksumMismatch { expected, got } =>
+                write!(f, "checksum mismatch: expected {expected:#010x}, got {got:#010x}"),
+        }
+    }
+}
+
+impl std::error::Error for LogError {}
+impl From<std::io::Error> for LogError {
+    fn from(e: std::io::Error) -> Self { LogError::Io(e) }
+}
+
+// BufReader for batched I/O syscalls; &Path for type-safe path (Ch 7)
+// Returns Result — caller decides how to handle failure (Ch 3)
+fn read_log(path: &Path) -> Result<Vec<u8>, LogError> {
+    let file = File::open(path)?;  // ? converts io::Error → LogError (Ch 8)
+    let mut reader = BufReader::new(file);  // batched reads (Ch 7)
+    let mut buf = Vec::new();
+    reader.read_to_end(&mut buf)?;
+    Ok(buf)
+}
+
+// Explicit little-endian — deterministic across all hosts (Ch 5, 7)
+fn parse_record_id(bytes: &[u8], offset: usize) -> Result<u32, LogError> {
+    bytes.get(offset..offset + 4)
+        .ok_or(LogError::InvalidRecord { offset, reason: "not enough bytes for id" })
+        .map(|b| u32::from_le_bytes(b.try_into().unwrap()))
+}
+
+// Simulate a simple CRC32-like checksum (Ch 7)
+fn checksum(data: &[u8]) -> u32 {
+    data.iter().fold(0u32, |acc, &b| acc.wrapping_add(b as u32))
+}
+
+// Explicit little-endian write + checksum (Ch 5, 7)
+fn write_record(id: u32, data: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(4 + data.len() + 4);
+    out.extend_from_slice(&id.to_le_bytes());  // SAFETY: LE is the protocol spec
+    out.extend_from_slice(data);
+    let crc = checksum(&out);
+    out.extend_from_slice(&crc.to_le_bytes());  // append checksum
+    out
+}
+
+fn read_record(buf: &[u8]) -> Result<(u32, &[u8]), LogError> {
+    let id = parse_record_id(buf, 0)?;
+    let payload = buf.get(4..buf.len() - 4)
+        .ok_or(LogError::InvalidRecord { offset: 4, reason: "too short for payload + checksum" })?;
+    let stored_crc = u32::from_le_bytes(buf[buf.len() - 4..].try_into().unwrap());
+    let computed = checksum(&buf[..buf.len() - 4]);
+    if computed != stored_crc {
+        return Err(LogError::ChecksumMismatch { expected: stored_crc, got: computed });
+    }
+    Ok((id, payload))
+}
+
+// Thread pool via channel — no unbounded thread spawning (Ch 10)
+type Job = Box<dyn FnOnce() + Send + 'static>;
+
+struct Pool {
+    tx: mpsc::Sender<Job>,
+}
+
+impl Pool {
+    fn new(workers: usize) -> Self {
+        let (tx, rx) = mpsc::channel::<Job>();
+        let rx = Arc::new(Mutex::new(rx));
+        for _ in 0..workers {
+            let rx = Arc::clone(&rx);
+            thread::spawn(move || loop {
+                match rx.lock().expect("mutex poisoned").recv() {
+                    Ok(job) => job(),
+                    Err(_) => break,  // sender dropped — shut down
+                }
+            });
+        }
+        Pool { tx }
+    }
+
+    fn submit(&self, job: impl FnOnce() + Send + 'static) {
+        self.tx.send(Box::new(job)).expect("pool closed");
+    }
+}
+
+// Safe shared error counter via Arc<Mutex<T>> (Ch 6, 10)
+fn make_error_counter() -> Arc<Mutex<u32>> {
+    Arc::new(Mutex::new(0))
+}
+
+fn record_error(counter: &Arc<Mutex<u32>>) {
+    *counter.lock().expect("mutex poisoned") += 1;
+}
+
+fn main() -> Result<(), LogError> {
+    let path = Path::new("data.log");
+    let bytes = read_log(path)?;
+
+    let id = parse_record_id(&bytes, 0)?;
+    println!("id: {id}");
+
+    let pool = Pool::new(4);
+    let errors = make_error_counter();
+
+    // move — closure owns record + error counter clone (Ch 10)
+    let record = bytes.clone();
+    let err_counter = Arc::clone(&errors);
+    pool.submit(move || {
+        println!("processing {} bytes, id={}", record.len(), id);
+        if record.len() < 8 {
+            record_error(&err_counter);
+        }
+    });
+
+    // Give threads time to finish (production code would use join handles)
+    std::thread::sleep(std::time::Duration::from_millis(10));
+    println!("errors: {}", errors.lock().unwrap());
+
+    Ok(())
+}
+```
+
+**Key improvements:**
+- `LogError` wraps all downstream errors with `From` impls — `?` converts automatically (Ch 3, 8)
+- `BufReader` batches file I/O syscalls — essential for large files (Ch 7)
+- `u32::from_le_bytes()` / `to_le_bytes()` — explicit endianness, correct across all hosts (Ch 5)
+- Checksum appended and verified on read — corruption is detectable (Ch 7)
+- Thread pool via `mpsc::channel` + `Arc<Mutex<Receiver>>` — bounded concurrency (Ch 10)
+- `Arc<Mutex<u32>>` replaces `unsafe static mut` — safe shared mutable state (Ch 6, 10)
+- `move` closures transfer ownership into threads — required for `'static` bound (Ch 10)
+- `&Path` instead of `String` for file path — type-safe, works with literals (Ch 7)

package/skills/rust-in-action/examples/before.md

@@ -0,0 +1,56 @@
+# Before: Rust in Action
+
+A systems utility that reads a binary log file, parses records, and processes them concurrently — with common systems-level anti-patterns.
+
+```rust
+use std::fs::File;
+use std::io::Read;
+use std::thread;
+
+// Silently panics on any I/O failure; no error type
+fn read_log(path: String) -> Vec<u8> {
+    let mut file = File::open(path).unwrap();
+    let mut buf = vec![];
+    file.read_to_end(&mut buf).unwrap();
+    buf
+}
+
+// Assumes native endianness — corrupts data on big-endian hosts
+fn parse_record_id(bytes: &[u8]) -> u32 {
+    let arr = [bytes[0], bytes[1], bytes[2], bytes[3]];
+    u32::from_ne_bytes(arr)  // native endian — wrong for protocol
+}
+
+// Spawns one thread per record — no pooling
+fn process_all(records: Vec<Vec<u8>>) {
+    for record in records {
+        thread::spawn(|| {
+            println!("processing {} bytes", record.len());
+        });
+    }
+    // No join — threads may not finish before main exits
+}
+
+// Shared mutable state with unsafe global
+static mut ERROR_COUNT: u32 = 0;
+
+fn record_error() {
+    unsafe {
+        ERROR_COUNT += 1;  // data race — undefined behavior
+    }
+}
+
+// No endianness comment, no checksum, no error type
+fn write_record(id: u32, data: &[u8]) -> Vec<u8> {
+    let mut out = vec![];
+    out.extend_from_slice(&id.to_ne_bytes()); // native endian — wrong
+    out.extend_from_slice(data);
+    out  // no checksum — corruption undetectable
+}
+
+fn main() {
+    let bytes = read_log(String::from("data.log"));
+    let id = parse_record_id(&bytes);
+    println!("id: {}", id);
+}
+```

package/skills/rust-in-action/references/practices-catalog.md

@@ -0,0 +1,346 @@
+# Rust in Action — Practices Catalog
+
+Systems-focused before/after examples from each chapter group.
+
+---
+
+## Ownership: Use References, Not Moves (Ch 4)
+
+**Before:**
+```rust
+fn print_log(data: Vec<u8>) {  // consumes — caller loses data
+    println!("{} bytes", data.len());
+}
+let log = vec![1u8, 2, 3];
+print_log(log);
+// log is gone — can't use it again
+```
+**After:**
+```rust
+fn print_log(data: &[u8]) {  // borrows a slice — Vec<u8> derefs to &[u8]
+    println!("{} bytes", data.len());
+}
+let log = vec![1u8, 2, 3];
+print_log(&log);
+println!("{log:?}");  // still valid
+```
+
+---
+
+## Ownership: Resolving Lifetime Issues (Ch 4)
+
+**Before:**
+```rust
+struct Config {
+    name: String,  // owned — always heap-allocates
+}
+```
+**After (borrow when caller controls data):**
+```rust
+struct Config<'a> {
+    name: &'a str,  // borrows — zero allocation if caller has the string
+}
+// Use when Config doesn't outlive the string it references
+```
+**Or (own when Config must be independent):**
+```rust
+struct Config {
+    name: String,  // owned — correct when Config outlives the source string
+}
+```
+
+---
+
+## Smart Pointers: Choosing the Right Type (Ch 6)
+
+```rust
+// Box<T>: heap allocation, single owner
+let boxed: Box<[u8]> = vec![1, 2, 3].into_boxed_slice();
+
+// Rc<T>: shared ownership, single thread only
+use std::rc::Rc;
+let shared = Rc::new(vec![1, 2, 3]);
+let clone1 = Rc::clone(&shared);  // cheap — increments refcount
+// let _ = thread::spawn(move || { clone1; });  // COMPILE ERROR: Rc is not Send
+
+// Arc<T>: shared ownership, multi-thread safe
+use std::sync::Arc;
+let arc = Arc::new(vec![1, 2, 3]);
+let arc2 = Arc::clone(&arc);  // idiomatic — explicit about cheapness
+thread::spawn(move || println!("{arc2:?}")).join().unwrap();
+
+// RefCell<T>: interior mutability, single thread, runtime checks
+use std::cell::RefCell;
+let cache: RefCell<Option<String>> = RefCell::new(None);
+*cache.borrow_mut() = Some("computed".into());
+
+// Cow<T>: clone-on-write — avoids allocation when only reading
+use std::borrow::Cow;
+fn process(input: &str) -> Cow<str> {
+    if input.contains("bad") {
+        Cow::Owned(input.replace("bad", "good"))  // allocates only when needed
+    } else {
+        Cow::Borrowed(input)  // zero allocation
+    }
+}
+```
+
+---
+
+## Data: Explicit Endianness (Ch 5, 7)
+
+**Before:**
+```rust
+fn parse_id(bytes: &[u8]) -> u32 {
+    u32::from_ne_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])  // native — wrong on BE hosts
+}
+fn write_id(id: u32) -> [u8; 4] {
+    id.to_ne_bytes()  // corrupts protocol on big-endian
+}
+```
+**After:**
+```rust
+// Protocol says: little-endian. Be explicit regardless of host.
+fn parse_id(bytes: &[u8], offset: usize) -> Result<u32, &'static str> {
+    bytes.get(offset..offset + 4)
+        .ok_or("buffer too short")
+        .map(|b| u32::from_le_bytes(b.try_into().unwrap()))
+}
+
+fn write_id(id: u32) -> [u8; 4] {
+    id.to_le_bytes()  // always little-endian — deterministic on all hosts
+}
+```
+
+---
+
+## Data: Bit Manipulation (Ch 5)
+
+```rust
+// Named constants for masks — self-documenting (Ch 5)
+const SIGN_BIT: u32      = 0x8000_0000;
+const EXPONENT_MASK: u32 = 0x7F80_0000;
+const MANTISSA_MASK: u32 = 0x007F_FFFF;
+
+fn dissect_f32(n: f32) -> (u32, u32, u32) {
+    let bits = n.to_bits();
+    let sign     = (bits & SIGN_BIT) >> 31;
+    let exponent = (bits & EXPONENT_MASK) >> 23;
+    let mantissa =  bits & MANTISSA_MASK;
+    (sign, exponent, mantissa)
+}
+```
+
+---
+
+## Files: Buffered I/O + serde (Ch 7)
+
+**Before:**
+```rust
+use std::fs::File;
+use std::io::Read;
+let mut f = File::open("data.bin").unwrap();
+let mut buf = vec![];
+f.read_to_end(&mut buf).unwrap();  // unbuffered + panics
+```
+**After:**
+```rust
+use std::fs::File;
+use std::io::{BufReader, Read};
+use std::path::Path;
+
+fn read_file(path: &Path) -> Result<Vec<u8>, std::io::Error> {
+    let f = File::open(path)?;
+    let mut reader = BufReader::new(f);  // batched syscalls
+    let mut buf = Vec::new();
+    reader.read_to_end(&mut buf)?;
+    Ok(buf)
+}
+
+// Structured serialization with serde + bincode (Ch 7)
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Record {
+    id: u64,
+    payload: Vec<u8>,
+}
+
+fn write_record(rec: &Record, path: &Path) -> Result<(), Box<dyn std::error::Error>> {
+    let f = File::create(path)?;
+    let writer = std::io::BufWriter::new(f);
+    bincode::serialize_into(writer, rec)?;
+    Ok(())
+}
+```
+
+---
+
+## Error Handling: Library Error Wrapping (Ch 8)
+
+```rust
+// Wrapping multiple downstream error types in one domain error (Ch 8)
+#[derive(Debug)]
+pub enum NetworkError {
+    Io(std::io::Error),
+    AddrParse(std::net::AddrParseError),
+    Timeout,
+}
+
+impl std::fmt::Display for NetworkError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            NetworkError::Io(e) => write!(f, "I/O: {e}"),
+            NetworkError::AddrParse(e) => write!(f, "address parse: {e}"),
+            NetworkError::Timeout => write!(f, "connection timed out"),
+        }
+    }
+}
+
+impl std::error::Error for NetworkError {}
+
+impl From<std::io::Error> for NetworkError {
+    fn from(e: std::io::Error) -> Self { NetworkError::Io(e) }
+}
+impl From<std::net::AddrParseError> for NetworkError {
+    fn from(e: std::net::AddrParseError) -> Self { NetworkError::AddrParse(e) }
+}
+
+fn connect(addr: &str) -> Result<std::net::TcpStream, NetworkError> {
+    let addr: std::net::SocketAddr = addr.parse()?;  // AddrParseError → NetworkError
+    let stream = std::net::TcpStream::connect(addr)?;  // io::Error → NetworkError
+    Ok(stream)
+}
+```
+
+---
+
+## Networking: State Machines with Enums (Ch 8)
+
+```rust
+#[derive(Debug, Clone, PartialEq)]
+enum TcpState {
+    Closed,
+    Listen,
+    SynReceived,
+    Established,
+    FinWait1,
+    Closed_,
+}
+
+impl TcpState {
+    fn on_syn(self) -> Result<Self, &'static str> {
+        match self {
+            TcpState::Listen => Ok(TcpState::SynReceived),
+            other => Err("SYN received in invalid state"),
+        }
+    }
+
+    fn on_ack(self) -> Result<Self, &'static str> {
+        match self {
+            TcpState::SynReceived => Ok(TcpState::Established),
+            other => Err("ACK received in invalid state"),
+        }
+    }
+}
+```
+
+---
+
+## Concurrency: Thread Pool via Channels (Ch 10)
+
+```rust
+use std::sync::{Arc, Mutex, mpsc};
+use std::thread;
+
+// move closure required — captures must be 'static (Ch 10)
+fn spawn_worker(id: usize, rx: Arc<Mutex<mpsc::Receiver<String>>>) {
+    thread::spawn(move || loop {  // move transfers rx into thread
+        let msg = rx.lock().expect("mutex poisoned").recv();
+        match msg {
+            Ok(s) => println!("worker {id}: {s}"),
+            Err(_) => break,
+        }
+    });
+}
+
+fn main() {
+    let (tx, rx) = mpsc::channel::<String>();
+    let rx = Arc::new(Mutex::new(rx));
+
+    for i in 0..4 {
+        spawn_worker(i, Arc::clone(&rx));
+    }
+
+    tx.send("hello".into()).unwrap();
+    tx.send("world".into()).unwrap();
+    drop(tx);  // close channel — workers will exit their loops
+    thread::sleep(std::time::Duration::from_millis(10));
+}
+```
+
+---
+
+## Time: Instant vs SystemTime + NTP Offset (Ch 9)
+
+```rust
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+// Instant for elapsed — monotonic, cannot go backwards (Ch 9)
+let start = Instant::now();
+do_work();
+println!("elapsed: {:?}", start.elapsed());
+
+// SystemTime for wall clock (can go backwards — don't use for elapsed)
+let unix_ts = SystemTime::now()
+    .duration_since(UNIX_EPOCH)
+    .expect("system clock before Unix epoch")
+    .as_secs();
+
+// NTP epoch conversion (Ch 9)
+// NTP counts from 1900-01-01; Unix counts from 1970-01-01
+const NTP_UNIX_OFFSET: u64 = 2_208_988_800;
+
+fn ntp_to_unix(ntp_seconds: u64) -> u64 {
+    ntp_seconds.saturating_sub(NTP_UNIX_OFFSET)
+}
+
+fn unix_to_ntp(unix_seconds: u64) -> u64 {
+    unix_seconds + NTP_UNIX_OFFSET
+}
+```
+
+---
+
+## Unsafe: Safe Abstraction Pattern (Ch 6)
+
+```rust
+// Wrap unsafe in a safe API — callers need not use unsafe (Ch 6)
+pub struct AlignedBuffer {
+    ptr: *mut u8,
+    len: usize,
+}
+
+impl AlignedBuffer {
+    pub fn new(len: usize) -> Self {
+        // SAFETY: len > 0, alignment is a power of 2, ptr checked for null
+        let layout = std::alloc::Layout::from_size_align(len, 64).unwrap();
+        let ptr = unsafe { std::alloc::alloc_zeroed(layout) };
+        assert!(!ptr.is_null(), "allocation failed");
+        AlignedBuffer { ptr, len }
+    }
+
+    pub fn as_slice(&self) -> &[u8] {
+        // SAFETY: ptr valid, len accurate, no mutable alias exists
+        unsafe { std::slice::from_raw_parts(self.ptr, self.len) }
+    }
+}
+
+impl Drop for AlignedBuffer {
+    fn drop(&mut self) {
+        // SAFETY: same layout as alloc, ptr not yet freed
+        let layout = std::alloc::Layout::from_size_align(self.len, 64).unwrap();
+        unsafe { std::alloc::dealloc(self.ptr, layout) }
+    }
+}
+```

package/skills/rust-in-action/scripts/review.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Rust in Action reviews.
+Usage: python review.py <file.rs>
+
+Scans a Rust source file for systems-programming anti-patterns from the book:
+endianness issues, unsafe shared state, missing buffered I/O, unwrap misuse,
+unbounded thread spawning, and incorrect smart pointer choices.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+CHECKS = [
+    (
+        r"from_ne_bytes|to_ne_bytes",
+        "Ch 5/7: Native endianness",
+        "use from_le_bytes/to_le_bytes or from_be_bytes/to_be_bytes to match the protocol spec",
+    ),
+    (
+        r"static\s+mut\s+\w+",
+        "Ch 6/10: static mut",
+        "data race risk — replace with Arc<Mutex<T>> or std::sync::atomic",
+    ),
+    (
+        r"\.unwrap\(\)",
+        "Ch 3: .unwrap()",
+        "panics on failure — use ?, .expect(\"reason\"), or match in production paths",
+    ),
+    (
+        r"unsafe\s*\{",
+        "Ch 6: unsafe block",
+        "ensure a safe abstraction wraps this; add a // SAFETY: comment explaining invariants",
+    ),
+    (
+        r"File::open|File::create",
+        "Ch 7: Unbuffered file I/O",
+        "wrap in BufReader::new()/BufWriter::new() to batch syscalls",
+    ),
+    (
+        r"thread::spawn",
+        "Ch 10: thread::spawn",
+        "if inside a loop, consider a thread pool (channel + Arc<Mutex<Receiver>>) instead of one thread per task",
+    ),
+    (
+        r"\bRc\s*::\s*(new|clone)\b",
+        "Ch 6: Rc usage",
+        "Rc is not Send — if shared across threads, replace with Arc",
+    ),
+    (
+        r"Box::new\(Vec\b|Box::new\(vec!",
+        "Ch 6: Box<Vec<T>>",
+        "Vec already heap-allocates — Box<Vec<T>> is double-indirection with no benefit; return Vec directly",
+    ),
+    (
+        r"\bexpect\s*\(\s*\)",
+        "Ch 3: .expect() with empty string",
+        "add a meaningful reason: .expect(\"what invariant was violated\")",
+    ),
+]
+
+
+def scan(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("//"):
+            continue  # skip comments
+        for pattern, label, advice in CHECKS:
+            if re.search(pattern, line):
+                findings.append({
+                    "line": lineno,
+                    "text": line.rstrip(),
+                    "label": label,
+                    "advice": advice,
+                })
+    return findings
+
+
+def group_by_label(findings: list[dict]) -> dict:
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+    return groups
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.rs>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    if path.suffix.lower() != ".rs":
+        print(f"Warning: expected a .rs file, got '{path.suffix}' — continuing anyway")
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+    findings = scan(source)
+    groups = group_by_label(findings)
+
+    print(sep("="))
+    print("RUST IN ACTION — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential anti-patterns across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:  # cap display at 5 per category
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more occurrence(s)")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Review chapters: Ch 3 (errors), Ch 5-7 (data/files), Ch 6 (pointers), Ch 10 (concurrency)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()