dinja_core/
lib.rs

1//! # Rust CMS - MDX Rendering Service Library
2//!
3//! A high-performance library for converting MDX (Markdown with JSX) to HTML and JavaScript.
4//! Extracts YAML frontmatter and transforms TSX to JavaScript using the Oxc compiler.
5//!
6//! ## Architecture Overview
7//!
8//! The library is organized into several key modules:
9//!
10//! - **`service`**: High-level batch rendering service with resource limits and error handling
11//! - **`mdx`**: MDX parsing, frontmatter extraction, and rendering pipeline orchestration
12//! - **`renderer`**: JavaScript runtime management using Deno Core for component rendering
13//! - **`transform`**: TSX/JSX to JavaScript transformation using Oxc compiler
14//! - **`models`**: Data structures for MDX content, components, and configuration
15//! - **`error`**: Domain-specific error types for MDX processing
16//!
17//! ### Rendering Pipeline
18//!
19//! ```text
20//! MDX Content
21//!     |
22//!     +-> Extract YAML Frontmatter
23//!     |
24//!     +-> Convert Markdown to HTML (with JSX support)
25//!     |
26//!     +-> Transform TSX to JavaScript (Oxc compiler)
27//!     |
28//!     +-> Render Component (Deno Core + engine)
29//!             |
30//!             +-> HTML/JavaScript Output
31//! ```
32//!
33//! ## Thread Safety
34//!
35//! This library uses thread-local storage for JavaScript runtimes because `JsRuntime` is not
36//! `Send` or `Sync`. Each thread maintains its own renderer pool. The library is designed to be
37//! used in a multi-threaded web server context where each request handler runs on its own thread.
38//!
39//! ```text
40//! Thread 1          Thread 2          Thread 3
41//!    |                 |                 |
42//!    +- Renderer Pool  +- Renderer Pool  +- Renderer Pool
43//!    |  (thread-local)  |  (thread-local)  |  (thread-local)
44//!    |                 |                 |
45//!    +- Request 1      +- Request 2      +- Request 3
46//! ```
47//!
48//! ## Performance Tuning
49//!
50//! ### Renderer Pool Configuration
51//!
52//! - **`max_cached_renderers`**: Controls how many renderers are cached per profile per thread.
53//!   Higher values reduce renderer creation overhead but increase memory usage.
54//!   Recommended: 2-4 for most workloads.
55//!
56//! - **Pool Warming**: Use `pool.warm()` to pre-create renderers and reduce first-request latency.
57//!
58//! ### Resource Limits
59//!
60//! Configure resource limits to prevent memory exhaustion:
61//!
62//! - **`max_batch_size`**: Maximum number of files in a batch (default: 1000)
63//! - **`max_mdx_content_size`**: Maximum MDX file size (default: 10 MB)
64//! - **`max_component_code_size`**: Maximum component code size (default: 1 MB)
65//!
66//! ### String Pre-allocation
67//!
68//! The library pre-allocates strings with estimated capacity to reduce reallocations.
69//! This is handled automatically, but understanding the approach helps with profiling.
70//!
71//! ## Security Considerations
72//!
73//!
74//! ### Resource Limits
75//!
76//! Resource limits prevent memory exhaustion but are **not security controls**. They are
77//! reliability measures. Security features like rate limiting, authentication, and input
78//! validation should be implemented at the HTTP/web layer.
79//!
80//! ### Component Code
81//!
82//! Component code is transformed and executed in the JavaScript runtime. Validate and sanitize
83//! component code before passing it to the library if it originates from untrusted sources.
84//!
85//! ## Usage Example
86//!
87//! ```no_run
88//! use dinja_core::service::{RenderService, RenderServiceConfig};
89//! use dinja_core::models::NamedMdxBatchInput;
90//!
91//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
92//! let config = RenderServiceConfig::from_env();
93//! let service = RenderService::new(config)?;
94//!
95//! let input = NamedMdxBatchInput {
96//!     settings: Default::default(),
97//!     mdx: std::collections::HashMap::new(),
98//!     components: None,
99//! };
100//!
101//! let outcome = service.render_batch(&input)?;
102//! # Ok(())
103//! # }
104//! ```
105
106#![deny(missing_docs)]
107
108pub mod error;
109#[cfg(feature = "http")]
110pub mod handlers;
111pub mod mdx;
112pub mod models;
113pub mod renderer;
114pub mod service;
115pub mod transform;
dinja_core/lib.rs

dinja_core/
lib.rs
