docs: add mdBook documentation site with Pages deploy#37
Merged
Conversation
Remove H1 headings from both files so that mdBook chapters can own the top-level heading via include directives without creating duplicate H1s. GitHub renders H2-first content correctly (uses filename as implicit title).
13 chapters covering installation, quick start, traffic capture, the discover-curate-generate pipeline, filtering, resource limits, strict mode, reports, CLI reference, mitmproxy/HAR formats, benchmarks, security model, and diagnostics. Includes CHANGELOG and CONTRIBUTING via include directives, mdbook-admonish CSS assets, and Cargo.toml exclude for book/docs to keep crate tarball lean.
Slim README from ~274 to ~92 lines. Detailed CLI reference tables, resource limits, diagnostics, supported formats, and migration guide now live in the book at arkptz.github.io/mitm2openapi/. Adds docs badge pointing to the published site.
The cap_fired and rejected counters exist in the report schema but are not wired to reader pipelines yet. Update strict-mode.md and reports.md to reflect actual runtime behavior and mark unused counters as reserved.
stream_input checked is_dir() before validate_input_path, but is_dir() follows symlinks — so a symlink to a directory bypassed the symlink rejection even with --allow-symlinks=false. Fix: check symlink_metadata() before the is_dir() branch. Also add _no_symlinks variants for directory iteration in both mitmproxy and HAR readers so individual entries inside a directory are checked too.
Add tests for: - symlink pointing to a directory is rejected by validate_input_path - symlinked .flow entries inside a directory are skipped - symlinked .har entries inside a directory are skipped
HAR reader passed headers through without size checks. Mitmproxy reader already enforced MAX_HEADER_NAME_SIZE (8 KiB, drop) and MAX_HEADER_VALUE_SIZE (64 KiB, truncate). Apply the same caps to HAR entries so the documented per-field limits are enforced uniformly.
Template YAML examples were missing the top-level x-path-templates key
that the tool actually writes. Also fix {parameter} -> {id} to match
the actual parameterization output (single param = {id}, multiple =
{id1}, {id2}, ...). Fix response merging description: request body
comes from first observation only.
The release workflow packages archives as mitm2openapi-<tag>-<target>, but the install docs used a URL without the version segment, which 404s.
The security docs claimed fd-based metadata checks prevent TOCTOU races. In reality, validate_input_path uses path-based symlink_metadata() and metadata() before opening the file. Document the small TOCTOU window honestly and note fd-based recheck as a future enhancement.
The report struct field is named 'rejected', not 'flow_rejected'. Fix the diagnostics reference table to match the actual JSON key.
The docs implied processing continues after a tnetstring parse error. In reality, the iterator sets done=true and the rest of the file is dropped. Clarify this in both resource-limits.md and diagnostics.md.
The 89 MB fixture takes ~2.7 s in Rust. 'Milliseconds' was misleading. Reference the benchmarks page with the real 17x speedup figure instead.
detect_format_score checks file extension first (3 pts) then content heuristics (2 pts). The docs said 'auto-detect from file content' which omitted the extension check.
The wrapper book/src/reference/benchmarks.md provides its own H1 (Performance & Benchmarks), so the included docs/benchmarks.md should not add another. Demote to H2 and remove the redundant heading. Note: bench.yml workflow may overwrite this file on the next run; the workflow template should be updated to match if needed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a complete mdBook-powered documentation site at https://arkptz.github.io/mitm2openapi/.
Migrates detailed content from README into 13 structured chapters covering installation,
traffic capture, the discover-curate-generate pipeline, CLI reference, resource limits,
strict mode, reports, formats, benchmarks, security model, and diagnostics.
Type of Change
Checklist
cargo fmt --allcleancargo clippy --all-targets --all-features -- -D warningscleancargo testpasses locallyCHANGELOG.mdunder[Unreleased](if user-facing)feat:,fix:,docs:, etc.)What's included
book/— mdBook scaffold withbook.toml,SUMMARY.md, and 13 chapter source files.github/workflows/docs.yml— build + Pages deploy workflowReview feedback addressed
Review found several doc-vs-code mismatches and two missing input validations. All corrected:
Code fixes:
is_dir()following symlinks)Doc corrections:
parse_errorcounter is currently populated;cap_fired/rejectedmarked as reservedx-path-templates:top-level key{parameter}→{id}(matches actual output)flow_rejected→rejected(matches struct field name)Testing
cargo test --libpasses (235 tests)cargo test --test securitypasses (8 tests including new symlink coverage)cargo build --releasesucceedscargo publish --dry-runcleanBefore merging
Enable GitHub Pages in Settings → Pages with Source = "GitHub Actions" (one-time manual step).