Imported from asg017/litestream-rust (AGENTS.md). Install upstream with npx skills add asg017/litestream-rust. Copyright stays with the author.

AGENTS.md — AI Agent Coding Guidelines

Project Overview

This is a Rust rewrite of Litestream, a disaster recovery tool for SQLite. It continuously replicates SQLite databases to cloud storage via WAL interception.

Workspace Structure

Multi-crate workspace under crates/. See PLAN.md for full architecture.

Coding Standards

Rust Style

• Run cargo fmt before every commit — no exceptions.
• Run cargo clippy -- -D warnings — treat all warnings as errors.
• Run cargo test — all tests must pass before committing.
• Use #[must_use] on functions returning Result or important values.
• Prefer thiserror for library error types, anyhow only in binaries.
• Use tracing for logging, never println! or eprintln! in library code.

Testing

• Every public function must have at least one test.
• Use #[cfg(test)] mod tests { ... } in the same file.
• Integration tests go in tests/ directory.
• Feature-gate cloud integration tests: #[cfg(feature = "integration-s3")] etc.
• Use object_store::memory::InMemory for storage tests (no mocking needed).

Architecture Rules

• Foundation crates (ritestream-sqlite, ritestream-wal, ritestream-ltx) must have zero async dependencies.
• ritestream-sqlite must be no_std compatible.
• All async code uses Tokio runtime.
• Storage backends implement ReplicaClient trait from ritestream-storage.
• Use CancellationToken for graceful shutdown, never std::process::exit().

Dependencies

• Minimize dependency count. Justify new deps in PR descriptions.
• Pin major versions in Cargo.toml ("1" not "*").
• No unsafe without a // SAFETY: comment explaining the invariant.

Git Workflow

• Commit messages: imperative mood, e.g., "Add WAL checksum validation"
• Small, focused commits. One logical change per commit.
• All commits must pass: cargo fmt --check && cargo clippy -- -D warnings && cargo test

Error Handling

• Library crates: define domain-specific error enums with thiserror.
• Binary crates: use anyhow::Result at the top level.
• Never panic in library code. Use Result everywhere.
• Include context in errors: .context("failed to read WAL header")

LTX Format

• LTX files have a 4-byte end-of-pages marker (0x00000000) between the last page frame and the 16-byte trailer.
• The trailer is always the last 16 bytes: [PostApplyChecksum: u64 BE] [FileChecksum: u64 BE].
• Go and Rust implementations must produce compatible files; see crates/ritestream-ltx/tests/cross_compat.rs for golden test fixtures.
• CRC-64 ECMA checksums cover header + page frames + end marker + PostApplyChecksum (not FileChecksum).

Documentation

• Doc comments (///) on all public items.
• Include examples in doc comments for complex APIs.
• Link to Go source when porting: /// Ported from: litestream/wal_reader.go:L42