Technical Debt Tracking

Tech Debts — Kroki-rs v0.0.2¶

Identified during pre-release code review. Ordered by impact × effort.

🔴 Critical¶

• TD-01: convert() and convert_to_file() are 95% duplicated (cli/mod.rs)

• TD-02: Font aggregation copy-pasted 4× (main.rs, cli, handlers)

• TD-03: WebP format-routing copy-pasted 3× (cli, handlers)

• TD-13: Timeout errors lose all context — no tool name, input size, or partial stderr (diagrams/mod.rs)

• TD-14: Spawn errors are generic — don’t identify which binary failed (diagrams/mod.rs)

• TD-15: Provider errors are opaque strings, not structured (all providers)

• TD-19: No input size limits anywhere — unbounded memory risk (handlers, cli)

🟠 Major¶

• TD-04: Capabilities re-discovered on every HTTP request (handlers.rs, cli)

• TD-05: Server uses println! instead of tracing (server/mod.rs)

• TD-06: Server discovers capabilities but discards them (server/mod.rs)

• TD-07: Configuration priority pattern not established (all providers) — deferred to v0.0.3

• TD-16: Server leaks internal errors to clients (handlers.rs)

• TD-17: No partial stderr capture on timeout (diagrams/mod.rs)

• TD-20: No output size validation (handlers, cli)

• TD-21: No format whitelist — arbitrary strings reach providers (handlers.rs)

[TD-30] Centralize Temp File Management¶

Description: Various providers (bpmn.rs, vega.rs) generate and manage their own temporary files and directories. Impact: Duplicate logic for cleanup and error handling. Potential for orphaned files if a process forcefully terminates. Remediation: Create a unified TempWorkspace utility that handles lifecycle management, guaranteeing cleanups via Drop traits and reducing boiler plate in generation routes.

[x] [TD-31] Playwright Instance Pooling & Universal Browser Renderer¶

Description: Subprocess execution of mermaid-cli or bpmn-to-image currently spins up isolated Puppeteer/Chromium instances for every conversion request. This carries an immense overhead that negatively scales memory footprint and latency. Impact: Launching headless Chromium is notoriously expensive. Doing it dynamically per HTTP request prevents high-throughput diagram rendering and severely heightens the risk of Out-of-Memory (OOM) scenarios or memory leaks on the server. Remediation:

1. Migration to Playwright: Standardize all browser-reliant generators (Mermaid, BPMN, potentially Excalidraw/Wavedrom) to use a unified Playwright engine instead of outdated puppeteer wrappers.

2. Instance Pooling: Implement an active pool of pre-warmed Playwright BrowserContext objects.

3. TTL Enforcement: Enforce a strict Time-To-Live (TTL) or request-limit per browser instance before it is gracefully recycled, eradicating zombie memory leaks.

4. Abstracted Evaluation: Instead of calling CLI binaries, Kroki-rs should natively orchestrate the unified browser pool and execute page.evaluate(...) for the respective JS libraries, maximizing performance and eliminating unnecessary disk I/O.

🟡 Moderate¶

• TD-08: WebpQuality accepted but ignored (image_converter.rs) — Lossy falls back to lossless with warning; needs webp crate for true lossy

• TD-09: Cache dir resolution duplicated 3× (cli, font_manager)

• TD-10: cmd.rs hardcodes -Tsvg ignoring format param

• TD-11: validate() is no-op on every provider

• TD-12: Verbose per-tool debug logging in capabilities.rs

• TD-18: VegaLite pipeline errors don’t identify which stage failed (vega.rs)

• TD-22: Unknown type (400) conflated with tool-not-installed (503) (handlers.rs)

• TD-23: decode() hides UTF-8 errors behind generic message (utils/mod.rs)

• TD-24: excalidraw.rs ignores format parameter

• TD-25: bpmn.rs, wavedrom.rs, ditaa.rs use blocking I/O in async

• TD-27: Batch exits 0 even with partial failures (cli/mod.rs)

🔵 Minor¶

• TD-28: Leftover TODO/exploratory comments (multiple files)

• TD-29: test_decode_debug uses println, never asserts (utils/mod.rs)

• TD-30: ditaa.rs format validation has dead code branch