Rust off Rails: Web Development Mastery

The Definitive Guide to Convention-Driven, AI-Era Web Applications in Rust

Introduction: A Framework Made of Decisions

1. The Paralysis That Rails Solved
2. When the Coder Is an Agent, Not a Person
3. Rust off Rails in One Paragraph
4. What This Book Will Teach You
5. What This Book Will Not Do
6. A Note on Versions and Accuracy
7. How to Read This Book

Part I: Foundations

Chapter 1: A Framework Made of Decisions

1. What Rust off Rails Actually Is
2. The Problem with Endless Deliberation
3. Standing on Giants: Rails, Phoenix and Rust
4. Convention Over Deliberation, Not Just Configuration
5. The Prime Directives: Rules That Shape Every App
6. Why This Paradigm Is New - and Why It Matters

Chapter 2: The Rust Web Landscape

1. Why Rust for Web Applications
2. The Ecosystem: Axum, Actix, Rocket and Warp
3. What “Type Safety” Means for Web Code
4. The Cost of Compilation and How We Manage It
5. When Rust Makes Sense and When It Does Not

Chapter 3: Environment and Toolchain Setup

1. Installing Rust and Essential Toolchain Components
2. The One-Line Installer: What It Actually Does
3. Manual Setup for Those Who Prefer Control
4. Verifying Your Installation
5. Platform Notes: Linux, macOS and Windows Considerations
6. Starting Your First Project

Part II: The Stack

Chapter 4: The Approved Stack - One Crate per Job

1. Selection Criteria: Training Data, Compile-Time Safety and Stability
2. The Core Stack: Tokio, Axum, SeaORM, Askama
3. Supporting Crates: Serialization, Time, Cryptography and CLI
4. The Frontend Stack: Tailwind, HTMX and the Alternatives
5. Forbidden Crates and Why They’re Banned
6. The Complete Cargo.toml

Chapter 5: Project Scaffolding and Directory Structure

1. Root Files: Cargo.toml, Dockerfile and Configuration
2. The src Tree: lib, main and Module Boundaries
3. Controllers, Models, Views and Their One-Way Dependencies
4. Templates, Assets and Static Files
5. Tests, Migrations and the Product Directory
6. How It All Fits Together

Chapter 6: Configuration, State and Environment

1. The Config Struct: Parsing Environment Exactly Once
2. Environment Modes: Development, Test, Production
3. Building AppState: What Middleware and Handlers Share
4. Secrets Hygiene: Where Secrets Live and How They Die
5. Fail Fast: Boot Validation and Common Pitfalls

Chapter 7: Routing: Mapping URLs to Actions

1. The routes.rs Architecture and Feature-Specific Routers
2. Resourceful Routes: RESTful Patterns and the Standard Actions
3. Path Parameters, Query Strings and Body Extractors
4. Nested Routes and Shallow Nesting
5. Frontend Mode Differences: HTMX, Inertia, SPA, API
6. Route Security and the Route Table

Chapter 8: Controllers: Thin Handlers, Clean Flow

1. Handler Signatures and the Argument Order Rule
2. State, Context and Authentication Extractors
3. Read Actions: Index, Show and Query Delegation
4. Write Actions: Create, Update, Destroy and Redirect Rules
5. Authorization and Security in Handlers
6. Common Pitfalls and How to Avoid Them

Chapter 9: Views and Templates with Askama

1. Page Structs and the Rendering Contract
2. Layouts: The Global Shell and Block System
3. Partials and Fragments: Reusable HTML with Type Safety
4. The Component Kit: Macros for Accessible UI
5. HTMX Integration: Boosted Navigation and Event Delegation
6. Forms: Reusable Components with Validation
7. Flash and Alerts: One-Time Messages
8. Dark Mode and Theming

Part III: Building Applications

Chapter 10: Models and the Data Layer

1. Entity Definitions: Mirroring the Migration Exactly
2. Parameters and Validation: Input Structs That Fail Loudly
3. CRUD Functions: create, update, destroy and Error Handling
4. Associations: belongs_to, has_many and Eager Loading
5. What Models Are Not Allowed to Do

Chapter 11: Migrations: Schema as Immutable History

1. Creating and Registering Migrations
2. The Migration Trait and Schema DSL
3. Zero-Downtime Migrations: The Expand-Contract Pattern
4. SQLite Limitations and Table Rebuilds
5. Testing Rollbacks and the Immutable History Rule

Chapter 12: Database Portability: SQLite and Postgres

1. Runtime Backend Selection via DATABASE_URL
2. Connection Pooling: Different Defaults for Different Engines
3. Transactions: BEGIN IMMEDIATE and the kernel::db::begin Rule
4. Raw SQL Escape Hatches and Backend-Specific Logic
5. Data Migration Between Backends

Part V: User Experience and Frontend

Chapter 13: Authentication and Session Management

1. The ACCOUNTS Setting: Composing Authentication Flows
2. Sessions: Tokens, Digests and Cookie Configuration
3. Password Reset: Rate Limits, Tokens and Session Revocation
4. Email Verification and the Anti-Hijack Rule
5. Invite-Only Mode and Signup Control
6. Rate Limiting and Login Protection

Chapter 14: HTMX-Driven Interfaces

1. Setting Up HTMX and Tailwind Without Node
2. Boosted Navigation: Links That Don’t Reload the Page
3. Handling Validation Errors and Redirect Rules
4. Partial Updates and Out-of-Band Swaps
5. JavaScript That Survives Swaps: Event Delegation Patterns

Chapter 15: Inertia Mode: React or Svelte with Rust Routing

1. The Inertia Protocol: JSON for Visits, HTML for Initial Load
2. Page Props, ts-rs Type Generation and the Large Int Rule
3. Frontend Setup: Vite, Pages and Routing
4. Forms with useForm and Server-Side Validation Errors
5. Asset Versioning and the 409 Reload

Chapter 16: SPA Mode: A React Frontend on a Rust API

1. Why SPA Mode: When You Actually Need a Public API
2. The API Boundary: /api/v1 and the No-Leakage Rule
3. Frontend Architecture: React Router 8 and Data Loading
4. State Management: TanStack Query and Cache Invalidation
5. Authentication Without JWT: Cookie Sessions in a SPA

Part VI: Production Readiness

Chapter 17: Background Jobs and the Persistent Queue

1. The Philosophy: The Database Is the Only Infrastructure
2. Defining Workers: Traits, Constants and the perform Method
3. Enqueueing: Jobs Inside Transactions and Lightweight Args
4. Retries, Backoff, Snoozing and Dead Letter Queues
5. Scheduling: Delayed Execution and Cron-Based Recurring Jobs
6. The Jobs Dashboard and CLI: Monitoring from Browser or Terminal

Chapter 18: Mailers and Email Delivery

1. The Email Struct: To, Subject, Parts and Attachments
2. Delivery Modes: SMTP, Local, Log and Memory
3. Templates: HTML and Text with Absolute URLs Only
4. Deliver Later: Asynchronous Sending and Token Minting at Send Time
5. The Local Mailbox: Rendering, Searching and Agent Verification

Chapter 19: Real-Time Updates and WebSockets

1. The Signal Model: Broadcast Signals, Not HTML
2. SSE Streams: Connections, Heartbeats and Resume Cursors
3. Pub/Sub: In-Process Notification and Postgres NOTIFY
4. Presence Tracking: People, Not Tabs
5. WebSocket Channels: Rooms, Protocols and Slow Consumer Handling

Chapter 20: Security: Defenses Against Common Attacks

1. CSRF: Fetch Metadata and Origin Validation
2. XSS: Auto-Escaping, Ammonia and Strict CSP
3. Injection: SeaORM Builders and No String Formatting for SQL
4. Authentication Security: Rate Limits, Session Revocation, Secrets Hygiene
5. Security Headers: CSP, HSTS and Cache-Control
6. Rate Limiting: Fixed Windows and Lockout Prevention
7. Development Security: localhost Binding and Host Header Checks

Chapter 21: Testing Strategies and the Definition of Done

1. Integration Tests: The TestApp and Simulating Browser Behavior
2. Model and Policy Tests: Truth Tables and Boundary Conditions
3. Factories and Fixtures: Reusable Test Data Without Mocking
4. Database Handling: In-Memory SQLite and Postgres Slot-Based Testing
5. Frontend Testing: Vitest, Playwright and Never Mocking Fetch
6. The Definition of Done: cargo offrails verify and What It Checks

Chapter 22: Error Handling, Logging and Observability

1. AppError: Variants, HTTP Mapping and the IntoResponse Implementation
2. Error Shaping: Different Responses for HTML, HTMX and JSON
3. Panic Handling: The Catch Layer and Generic 500 Pages
4. Logging with tracing-subscriber: Structured Events and Levels
5. Spans, Instrumentation and What to Skip
6. Health Checks: The /up Endpoint and Database Verification

Chapter 23: Caching: When, Where and How

1. The Philosophy: Do Not Cache Until Measured
2. Architecture: Moka in Memory, cache_entries in the Database
3. Key Design: Versioning with updated_at and Prefix Deletion
4. Invalidation: What You Can and Cannot Do in Transactions
5. What Never to Cache: HTML, Flash, Forms, User-Specific Data

Chapter 24: File Storage and Uploads

1. Architecture: object_store and the blobs Metadata Table
2. Backends: Local Disk, Memory and S3-Compatible Services
3. Upload Handling: Multipart Extractors and Body Size Limits
4. Serving and Security: Authorization Through the App, Not Direct URLs
5. Async Deletion: Jobs That Clean Up After Transactions

Chapter 25: API Documentation and GraphQL

1. OpenAPI with utoipa: Annotations, Schemas and Security Schemes
2. API Versioning: /api/v1, /api/v2 and the No-Breaking-Changes Rule
3. Schema Management: Committing the Document and Drift Tests
4. GraphQL: Schema, Resolvers and DataLoaders
5. Complexity Limits, Depth Guards and Security

Part VII: Operations and Scaling

Chapter 26: Deployment: Docker, Platforms and Zero-Downtime Releases

1. The Docker Image: One Container, Web and Worker
2. Multi-Stage Builds: Rust Toolchain, Node and Runtime
3. Platform Configurations: Fly.io, Kamal, Render, Railway
4. Database Migrations in Production: Release Commands and Advisory Locks
5. Health Checks, Rolling Deploys and Rollback Strategies
6. Open-Source and Secret Management

Chapter 27: CI/CD, Code Quality and Long-Term Maintenance

1. The CI Pipeline: Parallel Verification and Database Testing
2. Code Quality: fmt, clippy, cargo-deny and gitleaks
3. Coverage and Mutation Testing: Thresholds and Enforced Gates
4. Browser and Accessibility Checks in CI
5. Upgrading: Framework Releases and the CHANGELOG as Guide

Chapter 28: Conclusion - The Shape of Things to Come

1. What We Have Built: The Complete Railboard Application
2. The Trade-Offs: Opinionation as Feature and as Constraint
3. When to Use Rust off Rails and When Not To
4. The Future: Where This Paradigm Is Heading
5. Go Build Something Real

References