forme-ruby 0.1.0 → 0.2.0

data/ext/forme_pdf/src/lib.rs

@@ -1,17 +1,36 @@
 //! Native result ownership boundary. Each call owns an independent result.
 use base64::{engine::general_purpose::STANDARD, Engine};
-use forme_pdf_html::{render_html, FontSpec, HtmlOptions};
+use forme::{
+    model::{Document, NodeKind},
+    render_with_options, RenderOptions,
+};
+use forme_pdf_html::{html_to_document, FontSpec, HtmlOptions};
+use html5ever::{parse_document, tendril::TendrilSink};
+use markup5ever_rcdom::{NodeData, RcDom};
 use serde::Deserialize;
 use std::{
+    collections::HashMap,
+    fs::File,
+    io::Read,
     panic::{catch_unwind, AssertUnwindSafe},
+    path::{Path, PathBuf},
     ptr, slice,
+    thread::{self, Builder},
 };
 
+/// Deepest element nesting accepted. Parsing, mapping and layout recurse per
+/// level, so deeper documents fail cleanly instead of overflowing the stack.
+const MAX_DEPTH: usize = 512;
+/// Renders run on their own thread: Ruby threads often have a 1 MiB stack.
+const RENDER_STACK_BYTES: usize = 64 << 20;
+const MAX_IMAGE_BYTES: u64 = 64 << 20;
+
 #[derive(Default, Deserialize)]
 #[serde(default, deny_unknown_fields)]
 struct Options {
     css: Option<String>,
     fonts: Vec<Font>,
+    image_root: Option<String>,
 }
 #[derive(Deserialize)]
 #[serde(deny_unknown_fields)]
@@ -41,6 +60,14 @@ impl RenderResult {
 fn render(html: &[u8], options: &[u8]) -> Result<RenderResult, String> {
     let html = std::str::from_utf8(html).map_err(|_| "HTML must be UTF-8")?;
     let input: Options = serde_json::from_slice(options).map_err(|e| e.to_string())?;
+    let image_root = input
+        .image_root
+        .map(|root| Path::new(&root).canonicalize())
+        .transpose()
+        .map_err(|_| "image_root must be a readable directory")?;
+    if nesting_depth(html) > MAX_DEPTH {
+        return Err(format!("HTML nesting exceeds {MAX_DEPTH} levels"));
+    }
     let mut opts = HtmlOptions {
         css: input.css,
         ..HtmlOptions::default()
@@ -60,18 +87,109 @@ fn render(html: &[u8], options: &[u8]) -> Result<RenderResult, String> {
             italic: font.italic,
         });
     }
-    let output = render_html(html, &opts).map_err(|e| e.to_string())?;
+    // forme_pdf_html::render_html, with file images resolved by this binding.
+    let (mut doc, mut warnings) = html_to_document(html, &opts);
+    resolve_local_images(&mut doc, image_root.as_deref(), &mut warnings);
+    let (pdf, engine_warnings, passes) = render_with_options(
+        &doc,
+        RenderOptions {
+            audit_content: opts.audit_content,
+        },
+    )
+    .map_err(|e| e.to_string())?;
+    warnings.extend(engine_warnings);
     let metadata = serde_json::to_vec(
-        &serde_json::json!({"warnings": output.warnings, "passes": output.passes}),
+        &serde_json::json!({"warnings": dedup_warnings(warnings), "passes": passes}),
     )
     .map_err(|e| e.to_string())?;
     Ok(RenderResult {
         status: 0,
-        pdf: output.pdf,
+        pdf,
         metadata,
         error: vec![],
     })
 }
+
+/// Element depth of the parsed DOM, measured without recursion.
+fn nesting_depth(html: &str) -> usize {
+    let dom = parse_document(RcDom::default(), Default::default()).one(html);
+    let mut deepest = 0;
+    // Hold `dom` until the walk ends: rcdom's iterative Drop empties child
+    // lists even while other handles still reference those children.
+    let mut pending = vec![(dom.document.clone(), 0)];
+    while let Some((node, depth)) = pending.pop() {
+        let depth = depth + usize::from(matches!(node.data, NodeData::Element { .. }));
+        deepest = deepest.max(depth);
+        pending.extend(node.children.borrow().iter().map(|c| (c.clone(), depth)));
+    }
+    deepest
+}
+
+/// The engine reads `/`, `./` and `../` image sources from disk itself. Inline
+/// them as data URIs when they resolve to a regular file inside `image_root`;
+/// otherwise omit the image. Warnings never echo paths or OS errors.
+fn resolve_local_images(doc: &mut Document, root: Option<&Path>, warnings: &mut Vec<String>) {
+    let mut pending: Vec<_> = doc.children.iter_mut().collect();
+    while let Some(node) = pending.pop() {
+        if let NodeKind::Image { src, .. } = &mut node.kind {
+            if src.starts_with('/') || src.starts_with("./") || src.starts_with("../") {
+                match local_image(src, root) {
+                    Ok(data) => *src = format!("data:image/*;base64,{}", STANDARD.encode(data)),
+                    Err(reason) => {
+                        warnings.push(format!("Local image omitted: {reason}"));
+                        src.clear();
+                    }
+                }
+            }
+        }
+        pending.extend(node.children.iter_mut());
+    }
+}
+
+fn local_image(src: &str, root: Option<&Path>) -> Result<Vec<u8>, &'static str> {
+    let root = root.ok_or("pass image_root to allow file images")?;
+    let path = if src.starts_with('/') {
+        PathBuf::from(src)
+    } else {
+        root.join(src)
+    };
+    let path = path.canonicalize().map_err(|_| "file not found")?;
+    if !path.starts_with(root) {
+        return Err("path is outside image_root");
+    }
+    let file = File::open(&path).map_err(|_| "file not readable")?;
+    if !file.metadata().map_err(|_| "file not readable")?.is_file() {
+        return Err("not a regular file");
+    }
+    let mut data = Vec::new();
+    file.take(MAX_IMAGE_BYTES + 1)
+        .read_to_end(&mut data)
+        .map_err(|_| "file not readable")?;
+    if data.len() as u64 > MAX_IMAGE_BYTES {
+        return Err("file exceeds 64 MiB");
+    }
+    Ok(data)
+}
+
+/// Same as forme_pdf_html's private helper: collapse repeats into "… (×N)".
+fn dedup_warnings(warnings: Vec<String>) -> Vec<String> {
+    let mut order = Vec::new();
+    let mut counts: HashMap<String, usize> = HashMap::new();
+    for warning in warnings {
+        let count = counts.entry(warning.clone()).or_insert(0);
+        if *count == 0 {
+            order.push(warning);
+        }
+        *count += 1;
+    }
+    order
+        .into_iter()
+        .map(|w| match counts[&w] {
+            1 => w,
+            n => format!("{w} (×{n})"),
+        })
+        .collect()
+}
 #[no_mangle]
 pub extern "C" fn forme_abi_version() -> u32 {
     1
@@ -105,7 +223,19 @@ pub unsafe extern "C" fn forme_render_html(
         } else {
             slice::from_raw_parts(options, options_len)
         };
-        render(h, o).unwrap_or_else(|e| RenderResult::error(1, e))
+        thread::scope(|scope| {
+            match Builder::new()
+                .name("forme-render".into())
+                .stack_size(RENDER_STACK_BYTES)
+                .spawn_scoped(scope, || render(h, o))
+            {
+                Ok(worker) => match worker.join() {
+                    Ok(output) => output.unwrap_or_else(|e| RenderResult::error(1, e)),
+                    Err(_) => RenderResult::error(2, "Native renderer panicked".into()),
+                },
+                Err(_) => RenderResult::error(1, "Cannot start render thread".into()),
+            }
+        })
     }))
     .unwrap_or_else(|_| RenderResult::error(2, "Native renderer panicked".into()));
     Box::into_raw(Box::new(output))
@@ -176,6 +306,71 @@ mod tests {
             forme_result_destroy(ptr::null_mut());
         }
     }
+    /// Render through the C ABI, as Ruby does: status and error text.
+    fn ffi_render(html: &str, options: &str) -> (i32, String) {
+        unsafe {
+            let r = forme_render_html(html.as_ptr(), html.len(), options.as_ptr(), options.len());
+            let mut len = 0;
+            let error = forme_result_bytes(r, 2, &mut len);
+            let error = String::from_utf8_lossy(slice::from_raw_parts(error, len)).into_owned();
+            let status = forme_result_status(r);
+            forme_result_destroy(r);
+            (status, error)
+        }
+    }
+    #[test]
+    fn nesting_limit() {
+        let nested = |depth: usize| "<div>".repeat(depth) + "x" + &"</div>".repeat(depth);
+        assert_eq!(nesting_depth(&nested(10)), 12);
+        assert_eq!(ffi_render(&nested(MAX_DEPTH - 2), "{}").0, 0);
+        let (status, error) = ffi_render(&nested(MAX_DEPTH), "{}");
+        assert_eq!(status, 1);
+        assert!(error.contains("nesting"));
+    }
+    #[test]
+    fn deep_render_on_small_caller_stack() {
+        let html = "<div>".repeat(MAX_DEPTH - 2);
+        let status = thread::Builder::new()
+            .stack_size(256 << 10)
+            .spawn(move || unsafe {
+                let r = forme_render_html(html.as_ptr(), html.len(), ptr::null(), 0);
+                let status = forme_result_status(r);
+                forme_result_destroy(r);
+                status
+            })
+            .unwrap()
+            .join()
+            .unwrap();
+        assert_eq!(status, 0);
+    }
+    #[test]
+    fn file_images_need_image_root() {
+        let html = br#"<img width="10" height="10" src="/etc/hosts">"#;
+        let metadata = render(html, b"{}").unwrap().metadata;
+        let metadata = String::from_utf8(metadata).unwrap();
+        assert!(metadata.contains("Local image omitted: pass image_root"));
+        assert!(!metadata.contains("/etc/hosts"));
+        let outside = render(html, br#"{"image_root":"/tmp"}"#).unwrap().metadata;
+        assert!(String::from_utf8(outside)
+            .unwrap()
+            .contains("outside image_root"));
+        assert!(render(html, br#"{"image_root":"/nonexistent/forme"}"#).is_err());
+    }
+    #[test]
+    fn result_accessors_reject_invalid_arguments() {
+        unsafe {
+            assert_eq!(forme_result_status(ptr::null()), 3);
+            let r = forme_render_html(b"hi".as_ptr(), 2, ptr::null(), 0);
+            let mut len = 7;
+            assert!(forme_result_bytes(r, 3, &mut len).is_null());
+            assert_eq!(len, 0);
+            assert!(forme_result_bytes(r, 0, ptr::null_mut()).is_null());
+            assert!(forme_result_bytes(ptr::null(), 0, &mut len).is_null());
+            assert!(!forme_result_bytes(r, 0, &mut len).is_null());
+            assert!(len > 0);
+            forme_result_destroy(r);
+        }
+    }
     #[test]
     fn parallel() {
         let tasks: Vec<_> = (0..8)

data/lib/forme_pdf/rails.rb

@@ -5,6 +5,8 @@ require "forme_pdf"
 module FormePDF
   # Explicitly include this module in an ActionController; no Railtie or middleware.
   module Rails
+    private
+
     # Render a caller-selected Rails template into binary PDF bytes.
     # The controller retains responsibility for authorization and send_data.
     def render_forme_pdf(template:, layout:, locals: {}, **options)

data/lib/forme_pdf/renderer.rb

@@ -6,19 +6,12 @@ module FormePDF
   # One native render call with caller-owned input and independently owned output.
   class Renderer
     # Return PDF bytes, renderer warnings and layout pass count.
-    def self.call(html, css: nil, fonts: [])
+    def self.call(html, css: nil, fonts: [], image_root: nil)
       fail ArgumentError, "HTML must be a String" unless html.is_a?(String)
-      html = html.dup
-      html.force_encoding(Encoding::UTF_8) if html.encoding == Encoding::BINARY
-      fail ArgumentError, "HTML must be valid UTF-8" unless html.valid_encoding?
-      html = html.encode(Encoding::UTF_8)
+      html = utf8(html, "HTML")
       fail ArgumentError, "CSS must be a String or nil" unless css.nil? || css.is_a?(String)
       fail ArgumentError, "fonts must be an Array" unless fonts.is_a?(Array)
-      options = JSON.generate(css: css, fonts: fonts.map { |font|
-        fail ArgumentError, "font must contain family and data" unless font.is_a?(Hash) && font[:family].is_a?(String) && font[:data].is_a?(String)
-        fail ArgumentError, "unknown font option" unless (font.keys - %i[family data weight italic]).empty?
-        {family: font.fetch(:family), data: Base64.strict_encode64(font.fetch(:data)), weight: font.fetch(:weight, 400), italic: font.fetch(:italic, false)}
-      })
+      options = JSON.generate(css: css && utf8(css, "CSS"), fonts: fonts.map { |font| font_option(font) }, image_root: image_root_option(image_root))
       Native.load!
       input = FFI::MemoryPointer.from_string(html)
       opts = FFI::MemoryPointer.from_string(options)
@@ -36,5 +29,32 @@ module FormePDF
         Native.forme_result_destroy(result) if result && !result.null?
       end
     end
+
+    # Binary text is read as UTF-8; other valid encodings are transcoded.
+    def self.utf8(text, name)
+      text = text.dup
+      text.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
+      fail ArgumentError, "#{name} must be valid UTF-8" unless text.valid_encoding?
+      text.encode(Encoding::UTF_8)
+    end
+
+    def self.font_option(font)
+      fail ArgumentError, "font must contain family and data" unless font.is_a?(Hash) && font[:family].is_a?(String) && font[:data].is_a?(String)
+      fail ArgumentError, "unknown font option" unless (font.keys - %i[family data weight italic]).empty?
+      weight = font.fetch(:weight, 400)
+      italic = font.fetch(:italic, false)
+      fail ArgumentError, "font weight must be an Integer from 1 to 1000" unless weight.is_a?(Integer) && weight.between?(1, 1000)
+      fail ArgumentError, "font italic must be true or false" unless [true, false].include?(italic)
+      {family: utf8(font[:family], "font family"), data: Base64.strict_encode64(font[:data]), weight: weight, italic: italic}
+    end
+
+    def self.image_root_option(root)
+      return if root.nil?
+      fail ArgumentError, "image_root must be a String or Pathname" unless root.is_a?(String) || root.respond_to?(:to_path)
+      root = File.expand_path(root.respond_to?(:to_path) ? root.to_path : root)
+      fail ArgumentError, "image_root must be an existing directory" unless File.directory?(root)
+      utf8(root, "image_root")
+    end
+    private_class_method :utf8, :font_option, :image_root_option
   end
 end

data/lib/forme_pdf/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module FormePDF
-  VERSION = "0.1.0"
-  ENGINE_REVISION = "f408920e632c59da0651b5b6d32f8c1397477673"
+  VERSION = "0.2.0"
+  ENGINE_REVISION = "b97dc101b705ea5d7fea6fb1b20fabfb5bd2d63d"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: forme-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ajaya Agrawalla
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -47,7 +47,7 @@ dependencies:
         version: '2.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -57,7 +57,7 @@ dependencies:
         version: '2.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4'
 description: Independent Ruby bindings for the Rust Forme HTML renderer. No browser,
   Node.js, WebAssembly or separate rendering service.
 email:
@@ -99,9 +99,9 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/clearstackio/forme-ruby
-  documentation_uri: https://github.com/clearstackio/forme-ruby/blob/main/docs/README.md
+  documentation_uri: https://github.com/clearstackio/forme-ruby/blob/master/docs/README.md
   bug_tracker_uri: https://github.com/clearstackio/forme-ruby/issues
-  changelog_uri: https://github.com/clearstackio/forme-ruby/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/clearstackio/forme-ruby/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org
 post_install_message: 
@@ -112,7 +112,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="