e2c1e2817b
This commit implements Phase 6.9.6: surfacing the cache as user-visible CLI and HTTP affordances. ## Changes - Add `pdftract cache` subcommand with stats/clear/purge actions - `stats DIR`: show entry count, size, hit ratio, age distribution - `stats DIR --json`: emit JSON with same fields - `clear DIR`: delete all entries (preserves index.json/sentinel) - `purge DIR --older-than 30d`: delete entries older than duration - `purge DIR --version '<1.0.0'`: version constraint purge (stub) - Add global flags to extract-style subcommands - `--cache-dir DIR`: enable cache at directory - `--cache-size SIZE`: set LRU size limit (default 1 GiB) - `--no-cache`: disable cache for this call - Add `X-Pdftract-Cache: hit|miss|skipped` HTTP header on /extract endpoints - Set in response headers before body streaming - Add JSON metadata fields - `metadata.cache_status`: "hit" | "miss" | "skipped" - `metadata.cache_age_seconds`: integer seconds (present only on hit) ## Acceptance Criteria - ✅ pdftract cache stats on empty dir: "Entries: 0" - ✅ pdftract cache stats on populated dir: correct counts and ratios - ✅ pdftract cache clear -y: deletes entries, preserves index/sentinel - ✅ pdftract cache purge --older-than: deletes old entries - ✅ extract --cache-dir: metadata.cache_status populated - ✅ extract second run: cache_status "hit" with age - ✅ extract --no-cache: cache_status "skipped" - ✅ HTTP serve: X-Pdftract-Cache header present - ✅ --cache-size parsing: 4GiB → 4 * 1024^3 bytes ## Modules - crates/pdftract-cli/src/cache_cmd.rs: subcommand implementation - crates/pdftract-cli/src/serve.rs: HTTP handler integration - crates/pdftract-cli/src/main.rs: CLI flag definitions - crates/pdftract-core/src/cache/mod.rs: extract_with_cache() integration - crates/pdftract-core/src/extract.rs: cache_status metadata fields Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| examples | ||
| proptest-regressions/parser/lexer | ||
| src | ||
| tests | ||
| __test__.pdf | ||
| Cargo.toml | ||
| pdftract-core.cdx.json | ||
| README.md | ||
pdftract-core
The core Rust library for PDF text extraction. This crate provides the parsing, layout analysis, font encoding recovery, and text extraction primitives used by the CLI (pdftract-cli) and Python bindings (pdftract-py).
Cargo.lock Policy
This workspace checks in Cargo.lock at the repository root. This is unconventional for library crates—the Cargo Book historically suggested that only binary crates should check in lockfiles, allowing library consumers to resolve their own dependency versions.
pdftract departs from this convention for release reproducibility:
-
SLSA Level 3 provenance requires that every milestone tag produces byte-identical artifacts across builds. Without a checked-in lockfile, two runs of
cargo buildon the same commit can resolve different transitive dependency versions, producing different binary hashes. -
Multi-output artifacts—this workspace produces Rust crates (
pdftract-core,pdftract-cli), Python wheels (pdftract-py), and Docker images. All must be built from the same dependency tree. -
Supply-chain security—the lockfile pins checksums for all transitive dependencies, enabling
cargo auditto detect yanked or compromised crates. -
Downstream consumers can still ignore the lockfile if needed. Cargo allows
cargo build --frozenwith a local lockfile override, or consumers can vendor the crate with their own dependency resolution.
The tradeoff—occasional merge conflicts when PRs update overlapping dependencies—is worth the guarantee of reproducible releases. See CONTRIBUTING.md for the lockfile-update workflow.
Modules
parser: PDF spec parsing (xref, trailer, object streams, indirect references)font: Font encoding recovery, glyph name lookup, fingerprintinglayout: Page layout analysis, region segmentation, reading orderextract: Text extraction with provenance (bounding boxes, confidence scores)ocr: Tesseract integration for raster pages
Usage
use pdftract_core::{extract_text, ExtractOptions};
let options = ExtractOptions::default();
let result = extract_text("document.pdf", &options)?;
println!("{}", result.text);