render: dot generation + svg pipeline + api image toolchain #9

Merged
nicolas_naranjo merged 1 commit from agent/render into master 2026-10-23 22:46:31 -05:00
Owner

Fulfills the [agent] render brief in docs/TASKS.md. Closes #6.

What changed

  • crates/rgxr-render/src/lib.rs — implemented both stubs (signatures unchanged):
    • to_dot(&Fa): deterministic DOT per BTree iteration order. Unlabeled point node → initial state (the automaton arrow), peripheries=2 on accepting states, one edge per (src, target) pair labeled with the comma-joined sorted symbol set ("a, b"). All state names/symbols emitted as quoted DOT strings with ", \\, \n, \r, \t escaped (user input). The arrow-source node name is picked to never collide with a user state (a state named __start bumps the node to ___start, etc.). Invalid FAs (failed Fa::validate) → RenderError::Dot, not a silently-wrong graph.
    • render_svg(fa, Fast): dot -Tsvg via tokio::process::Command, stdin-fed, stdout captured, 5s hard timeout (kill_on_drop(true)), nonzero exit → RenderError::Failed with a 500-char stderr snippet. Spawn failure (no graphviz) → RenderError::Unavailable("dot").
    • render_svg(fa, Latex): gated on RGXR_LATEX_ENABLED (unset/false/0/no/off → Unavailable("latex"); default off per contract). Pipeline: dot2tex --format=tikz → extract the tikzpicture → wrap in a minimal standalone doc → pdflatex -interaction=nonstopmode -halt-on-error → dvisvgm --pdf --no-fonts → read SVG. 20s hard timeout per subprocess, everything in a tempfile scratch dir, clean propagation of every failure as Failed/Unavailable.
  • crates/rgxr-render/Cargo.toml — added tempfile = "3" (explicit version, inside this crate only; root manifest untouched).
  • deploy/api.Dockerfile — build stage untouched; runtime stage adds python3, dot2tex, texlive-latex-base, texlive-latex-recommended, texlive-latex-extra, texlive-pictures, texlive-extra-utils, dvisvgm. dvisvgm pulls libgs10 transitively (needed for --pdf), so no explicit ghostscript package.
  • Tests: 12 in this crate (golden DOT test on the CONTRACT example FA, determinism, escaping, start-node collision, invalid-FA rejection, latex double-style variant, tikzpicture extraction, fast-path SVG, latex gating + pipeline, timeout, nonzero-exit, stderr truncation) + the crate-root cfg_attr test exemption. Workspace tests: 19 green.

Docker verification (real build + in-container checks)

  • docker build -f deploy/api.Dockerfile -t rgxr-api:dev . from the worktree root: success, image is 814 MB (target < 2GB).
  • The api on master has no /render route at all yet (not even 501 — the api PR is in flight), so per the brief I verified the toolchain directly in the container:
    • fast: echo "digraph{a->b}" | dot -Tsvg → <?xml version="1.0" ...?> ✓
    • latex: full pipeline (dot2tex 2.11.3 → pdflatex TeX Live 2022 → dvisvgm 3.0.3 --pdf --no-fonts) on the exact to_dot output of the CONTRACT example FA → valid SVG, tightly cropped (290×66pt) ✓
  • Once the api PR lands, POST /render should work in this image out of the box for engine=fast; engine=latex needs RGXR_LATEX_ENABLED=true in the environment (compose does not set it yet — integrator call, see semantic decisions).

Gate results

  • cargo fmt --check ✅
  • cargo clippy --workspace --all-targets ✅ 0 warnings
  • cargo test --workspace ✅ 19 passed (7 core + 12 render)

Semantic decisions (flag for review)

  1. Edge label separator is ", " (comma+space) — brief says "comma-joined"; CONTRACT only specifies "," for derived state names, which is a different context. Rendered labels read better with the space. Golden test pins it.
  2. to_dot validates the FA first (RenderError::Dot on failure). Rationale: rendering an FA with undeclared transition targets would silently draw a graph that disagrees with the wire data. The api can still 400 before calling render by validating itself (which the openapi flow implies).
  3. dvisvgm --pdf flag added (brief/contract just say dvisvgm): pdflatex emits PDF, and dvisvgm needs --pdf for PDF input. bookworm's dvisvgm 3.0.3 handles it fine via libgs10.
  4. tikzpicture extraction + own standalone wrapper: dot2tex's output template is version-dependent — 2.12 (host) wraps in standalone, bookworm's 2.11.3 wraps in a full-page article (\enlargethispage{100cm} → A4-sized SVG with a tiny graph in the corner). Extracting the picture and wrapping it ourselves gives tight crops on both.
  5. Latex path feeds dot2tex style="double" on accepting states (dot2tex drops peripheries but passes DOT style through to tikz) so the accepting double ring survives the tikz conversion. The public to_dot output keeps canonical peripheries=2 only — golden test pins that.
  6. RGXR_LATEX_ENABLED accepted truthy values: 1/true/yes/on (case-insensitive) enable; anything else, incl. unset/empty/non-UTF-8, disables (contract default).
  7. Missing dot binary on the fast path → Unavailable("dot") (→ 503 render_unavailable) rather than Failed; matches the contract's semantics for unrenderable-deployment, while actual tool failures/timeouts stay Failed (→ 500 internal).
  8. compose note: deploy/docker-compose.yml doesn)t set RGXR_LATEX_ENABLED; now that the image ships texlive, the integrator may flip it on there (default stays false per contract — I did not touch compose, it)s outside my ownership).
Fulfills the `[agent] render` brief in docs/TASKS.md. Closes #6. ## What changed - **`crates/rgxr-render/src/lib.rs`** — implemented both stubs (signatures unchanged): - `to_dot(&Fa)`: deterministic DOT per BTree iteration order. Unlabeled point node → initial state (the automaton arrow), `peripheries=2` on accepting states, one edge per (src, target) pair labeled with the comma-joined sorted symbol set (`"a, b"`). All state names/symbols emitted as quoted DOT strings with `"`, `\\`, `\n`, `\r`, `\t` escaped (user input). The arrow-source node name is picked to never collide with a user state (a state named `__start` bumps the node to `___start`, etc.). Invalid FAs (failed `Fa::validate`) → `RenderError::Dot`, not a silently-wrong graph. - `render_svg(fa, Fast)`: `dot -Tsvg` via `tokio::process::Command`, stdin-fed, stdout captured, 5s hard timeout (`kill_on_drop(true)`), nonzero exit → `RenderError::Failed` with a 500-char stderr snippet. Spawn failure (no graphviz) → `RenderError::Unavailable("dot")`. - `render_svg(fa, Latex)`: gated on `RGXR_LATEX_ENABLED` (unset/false/0/no/off → `Unavailable("latex")`; default off per contract). Pipeline: `dot2tex --format=tikz` → extract the `tikzpicture` → wrap in a minimal `standalone` doc → `pdflatex -interaction=nonstopmode -halt-on-error` → `dvisvgm --pdf --no-fonts` → read SVG. 20s hard timeout per subprocess, everything in a `tempfile` scratch dir, clean propagation of every failure as `Failed`/`Unavailable`. - **`crates/rgxr-render/Cargo.toml`** — added `tempfile = "3"` (explicit version, inside this crate only; root manifest untouched). - **`deploy/api.Dockerfile`** — build stage untouched; runtime stage adds `python3`, `dot2tex`, `texlive-latex-base`, `texlive-latex-recommended`, `texlive-latex-extra`, `texlive-pictures`, `texlive-extra-utils`, `dvisvgm`. `dvisvgm` pulls `libgs10` transitively (needed for `--pdf`), so no explicit ghostscript package. - Tests: 12 in this crate (golden DOT test on the CONTRACT example FA, determinism, escaping, start-node collision, invalid-FA rejection, latex double-style variant, tikzpicture extraction, fast-path SVG, latex gating + pipeline, timeout, nonzero-exit, stderr truncation) + the crate-root `cfg_attr` test exemption. Workspace tests: 19 green. ## Docker verification (real build + in-container checks) - `docker build -f deploy/api.Dockerfile -t rgxr-api:dev .` from the worktree root: **success, image is 814 MB** (target < 2GB). - The api on master has no `/render` route at all yet (not even 501 — the api PR is in flight), so per the brief I verified the toolchain **directly in the container**: - fast: `echo "digraph{a->b}" | dot -Tsvg` → `<?xml version="1.0" ...?>` ✓ - latex: full pipeline (dot2tex 2.11.3 → pdflatex TeX Live 2022 → dvisvgm 3.0.3 `--pdf --no-fonts`) on the exact `to_dot` output of the CONTRACT example FA → valid SVG, tightly cropped (290×66pt) ✓ - Once the api PR lands, `POST /render` should work in this image out of the box for `engine=fast`; `engine=latex` needs `RGXR_LATEX_ENABLED=true` in the environment (compose does not set it yet — integrator call, see semantic decisions). ## Gate results - `cargo fmt --check` ✅ - `cargo clippy --workspace --all-targets` ✅ 0 warnings - `cargo test --workspace` ✅ 19 passed (7 core + 12 render) ## Semantic decisions (flag for review) 1. **Edge label separator is `", "` (comma+space)** — brief says "comma-joined"; CONTRACT only specifies `","` for *derived state names*, which is a different context. Rendered labels read better with the space. Golden test pins it. 2. **`to_dot` validates the FA first** (`RenderError::Dot` on failure). Rationale: rendering an FA with undeclared transition targets would silently draw a graph that disagrees with the wire data. The api can still 400 before calling render by validating itself (which the openapi flow implies). 3. **`dvisvgm --pdf` flag added** (brief/contract just say `dvisvgm`): pdflatex emits PDF, and dvisvgm needs `--pdf` for PDF input. bookworm's dvisvgm 3.0.3 handles it fine via libgs10. 4. **tikzpicture extraction + own `standalone` wrapper**: dot2tex's output template is version-dependent — 2.12 (host) wraps in `standalone`, bookworm's 2.11.3 wraps in a full-page `article` (`\enlargethispage{100cm}` → A4-sized SVG with a tiny graph in the corner). Extracting the picture and wrapping it ourselves gives tight crops on both. 5. **Latex path feeds dot2tex `style="double"` on accepting states** (dot2tex drops `peripheries` but passes DOT `style` through to tikz) so the accepting double ring survives the tikz conversion. The public `to_dot` output keeps canonical `peripheries=2` only — golden test pins that. 6. **`RGXR_LATEX_ENABLED` accepted truthy values**: `1`/`true`/`yes`/`on` (case-insensitive) enable; anything else, incl. unset/empty/non-UTF-8, disables (contract default). 7. **Missing `dot` binary on the fast path → `Unavailable("dot")`** (→ 503 `render_unavailable`) rather than `Failed`; matches the contract's semantics for unrenderable-deployment, while actual tool failures/timeouts stay `Failed` (→ 500 `internal`). 8. **compose note**: `deploy/docker-compose.yml` doesn)t set `RGXR_LATEX_ENABLED`; now that the image ships texlive, the integrator may flip it on there (default stays `false` per contract — I did not touch compose, it)s outside my ownership).
render: dot generation, svg pipelines, api image toolchain
Some checks failed
ci / rust (pull_request) Failing after 3s
ci / web (pull_request) Successful in 42m35s
a2082c5f1e
- to_dot: deterministic DOT from Fa — initial arrow via a
  collision-free point node, peripheries=2 for accepting states,
  per-(src,target) edges labeled with comma-joined sorted symbol
  sets, quoted+escaped user input, validate() gate (RenderError::Dot)
- render_svg fast: dot -Tsvg via tokio::process, 5s hard timeout,
  kill_on_drop, Failed on nonzero exit with truncated stderr snippet
- render_svg latex: dot2tex --format=tikz -> extract tikzpicture ->
  standalone wrapper -> pdflatex -> dvisvgm --pdf --no-fonts, 20s per
  step, gated on RGXR_LATEX_ENABLED (default off per contract);
  style="double" added for accepting states since dot2tex drops
  peripheries
- deploy/api.Dockerfile: runtime layer adds python3, dot2tex,
  texlive-latex-{base,recommended,extra}, texlive-pictures,
  texlive-extra-utils, dvisvgm (814MB image); both render paths
  verified inside the built image

Closes #6
nicolas_naranjo force-pushed agent/render from a2082c5f1e
Some checks failed
ci / rust (pull_request) Failing after 3s
ci / web (pull_request) Successful in 42m35s
to da2d18f274
Some checks failed
ci / web (pull_request) Failing after 25m57s
ci / rust (pull_request) Has been cancelled
2026-10-23 22:46:22 -05:00
Compare
nicolas_naranjo deleted branch agent/render 2026-10-23 22:46:31 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
k8s-services/rgxr!9
No description provided.