forme-ruby 0.1.0

data/ext/forme_pdf/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "forme-pdf-native"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+[lib]
+name = "forme_pdf_native"
+crate-type = ["cdylib", "rlib"]
+[dependencies]
+forme-pdf-html = { git = "https://github.com/danmolitor/forme", rev = "f408920e632c59da0651b5b6d32f8c1397477673" }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+base64 = "0.22"
+ttf-parser = "0.25"
+[profile.release]
+panic = "unwind"

data/ext/forme_pdf/extconf.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+require "open3"
+require "json"
+require "tempfile"
+
+keep_build = ARGV.delete("--keep-build")
+Dir.chdir(__dir__) do
+  abort "forme-ruby source installation requires Rust/Cargo. Install a supported platform gem or install Rust first." unless system("cargo", "--version", out: File::NULL)
+  output, status = Open3.capture2("cargo", "build", "--locked", "--release", "--message-format=json", "--target-dir", File.join(__dir__, "target"), "--manifest-path", File.join(__dir__, "Cargo.toml"))
+  abort "Forme native build failed" unless status.success?
+  extension = RbConfig::CONFIG["host_os"].include?("darwin") ? "dylib" : "so"
+  artifacts = output.lines.filter_map do |line|
+    record = JSON.parse(line)
+    record.fetch("filenames", []) if record["reason"] == "compiler-artifact" && record.dig("target", "name") == "forme_pdf_native"
+  end.flatten
+  source = artifacts.find { |path| File.basename(path) == "libforme_pdf_native.#{extension}" }
+  abort "Cargo did not produce a Forme shared library for this platform" unless source
+  destination = File.expand_path("../../lib/forme_pdf/native", __dir__)
+  FileUtils.mkdir_p(destination)
+  # Replace the inode atomically: overwriting a loaded signed dylib breaks macOS code-signing caches.
+  Tempfile.create(["forme-native-", ".tmp"], destination) do |temporary|
+    FileUtils.cp(source, temporary.path)
+    temporary.chmod(0o644)
+    File.rename(temporary.path, File.join(destination, File.basename(source)))
+  end
+  FileUtils.rm_rf(File.join(__dir__, "target")) unless keep_build
+  File.write("Makefile", "all:\n\t@true\ninstall:\n\t@true\nclean:\n\t@true\n")
+end

data/ext/forme_pdf/src/lib.rs

@@ -0,0 +1,191 @@
+//! 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 serde::Deserialize;
+use std::{
+    panic::{catch_unwind, AssertUnwindSafe},
+    ptr, slice,
+};
+
+#[derive(Default, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+struct Options {
+    css: Option<String>,
+    fonts: Vec<Font>,
+}
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct Font {
+    family: String,
+    data: String,
+    weight: u32,
+    italic: bool,
+}
+
+pub struct RenderResult {
+    status: i32,
+    pdf: Vec<u8>,
+    metadata: Vec<u8>,
+    error: Vec<u8>,
+}
+impl RenderResult {
+    fn error(status: i32, message: String) -> Self {
+        Self {
+            status,
+            pdf: vec![],
+            metadata: vec![],
+            error: message.into_bytes(),
+        }
+    }
+}
+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 mut opts = HtmlOptions {
+        css: input.css,
+        ..HtmlOptions::default()
+    };
+    for font in input.fonts {
+        let data = STANDARD
+            .decode(font.data)
+            .map_err(|_| "Invalid font Base64")?;
+        ttf_parser::Face::parse(&data, 0).map_err(|_| "Invalid font data")?;
+        if font.family.is_empty() || !(1..=1000).contains(&font.weight) {
+            return Err("Invalid font family or weight".into());
+        }
+        opts.fonts.push(FontSpec {
+            family: font.family,
+            data,
+            weight: font.weight,
+            italic: font.italic,
+        });
+    }
+    let output = render_html(html, &opts).map_err(|e| e.to_string())?;
+    let metadata = serde_json::to_vec(
+        &serde_json::json!({"warnings": output.warnings, "passes": output.passes}),
+    )
+    .map_err(|e| e.to_string())?;
+    Ok(RenderResult {
+        status: 0,
+        pdf: output.pdf,
+        metadata,
+        error: vec![],
+    })
+}
+#[no_mangle]
+pub extern "C" fn forme_abi_version() -> u32 {
+    1
+}
+
+/// Render valid caller-owned buffers; null input is allowed only at length zero.
+/// # Safety
+/// Non-null pointers must address readable buffers of the supplied lengths.
+#[no_mangle]
+pub unsafe extern "C" fn forme_render_html(
+    html: *const u8,
+    html_len: usize,
+    options: *const u8,
+    options_len: usize,
+) -> *mut RenderResult {
+    let output = catch_unwind(AssertUnwindSafe(|| {
+        if (html.is_null() && html_len != 0)
+            || (options.is_null() && options_len != 0)
+            || html_len > isize::MAX as usize
+            || options_len > isize::MAX as usize
+        {
+            return RenderResult::error(1, "Invalid input buffer".into());
+        }
+        let h = if html_len == 0 {
+            &[]
+        } else {
+            slice::from_raw_parts(html, html_len)
+        };
+        let o = if options_len == 0 {
+            b"{}"
+        } else {
+            slice::from_raw_parts(options, options_len)
+        };
+        render(h, o).unwrap_or_else(|e| RenderResult::error(1, e))
+    }))
+    .unwrap_or_else(|_| RenderResult::error(2, "Native renderer panicked".into()));
+    Box::into_raw(Box::new(output))
+}
+/// # Safety
+/// Result must be a live handle returned by forme_render_html, or null.
+#[no_mangle]
+pub unsafe extern "C" fn forme_result_status(result: *const RenderResult) -> i32 {
+    result.as_ref().map_or(3, |r| r.status)
+}
+/// Borrow result bytes: field 0 = PDF, 1 = metadata JSON, 2 = error UTF-8.
+/// # Safety
+/// Result must be live and len must point to writable size_t storage.
+#[no_mangle]
+pub unsafe extern "C" fn forme_result_bytes(
+    result: *const RenderResult,
+    field: u32,
+    len: *mut usize,
+) -> *const u8 {
+    if len.is_null() {
+        return ptr::null();
+    }
+    *len = 0;
+    let Some(r) = result.as_ref() else {
+        return ptr::null();
+    };
+    let bytes = match field {
+        0 => &r.pdf,
+        1 => &r.metadata,
+        2 => &r.error,
+        _ => return ptr::null(),
+    };
+    *len = bytes.len();
+    bytes.as_ptr()
+}
+/// # Safety
+/// Handle must be null or a live allocation from forme_render_html, destroyed once.
+#[no_mangle]
+pub unsafe extern "C" fn forme_result_destroy(result: *mut RenderResult) {
+    if !result.is_null() {
+        drop(Box::from_raw(result));
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn pdf() {
+        assert!(render(b"<p>hello</p>", b"{}")
+            .unwrap()
+            .pdf
+            .starts_with(b"%PDF-"));
+    }
+    #[test]
+    fn invalid_utf8() {
+        assert!(render(&[255], b"{}").is_err());
+    }
+    #[test]
+    fn unknown_option() {
+        assert!(render(b"hi", br#"{"typo":1}"#).is_err());
+    }
+    #[test]
+    fn null_buffer() {
+        unsafe {
+            let r = forme_render_html(ptr::null(), 1, ptr::null(), 0);
+            assert_ne!(forme_result_status(r), 0);
+            forme_result_destroy(r);
+            forme_result_destroy(ptr::null_mut());
+        }
+    }
+    #[test]
+    fn parallel() {
+        let tasks: Vec<_> = (0..8)
+            .map(|i| {
+                std::thread::spawn(move || {
+                    render(format!("<p>{i}</p>").as_bytes(), b"{}").unwrap().pdf
+                })
+            })
+            .collect();
+        let pdfs: Vec<_> = tasks.into_iter().map(|t| t.join().unwrap()).collect();
+        assert_ne!(pdfs[0], pdfs[1]);
+    }
+}

data/lib/forme_pdf/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module FormePDF
+  class Error < StandardError; end
+  class RenderError < Error; end
+  class LoadError < Error; end
+end

data/lib/forme_pdf/native.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ffi"
+module FormePDF
+  # Loads only a library supplied by this gem's build or package.
+  module Native
+    extend FFI::Library
+
+    @load_mutex = Mutex.new
+
+    # Load once and validate the versioned C ABI before use.
+    def self.load!
+      @load_mutex.synchronize do
+        return if @loaded
+        extension = FFI::Platform.mac? ? "dylib" : "so"
+        path = File.expand_path("native/libforme_pdf_native.#{extension}", __dir__)
+        fail FormePDF::LoadError, "Forme native library missing; reinstall forme-ruby for your platform (source installs require Rust/Cargo)" unless File.file?(path)
+        ffi_lib path
+        attach_function :forme_abi_version, [], :uint32
+        fail FormePDF::LoadError, "Incompatible Forme native ABI" unless forme_abi_version == 1
+        attach_function :forme_render_html, [:pointer, :size_t, :pointer, :size_t], :pointer, blocking: true
+        attach_function :forme_result_status, [:pointer], :int32
+        attach_function :forme_result_bytes, [:pointer, :uint32, :pointer], :pointer
+        attach_function :forme_result_destroy, [:pointer], :void
+        @loaded = true
+      end
+    rescue ::LoadError => e
+      fail FormePDF::LoadError, "Cannot load Forme native library: #{e.message}"
+    end
+
+    # Copy a borrowed native buffer before its owning result is destroyed.
+    def self.copy(result, field)
+      length = FFI::MemoryPointer.new(:size_t)
+      pointer = forme_result_bytes(result, field, length)
+      size = length.read(:size_t)
+      return "".b if size.zero?
+      fail FormePDF::RenderError, "Native result has a null buffer" if pointer.null?
+      pointer.read_string_length(size).b
+    end
+  end
+end

data/lib/forme_pdf/rails.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "forme_pdf"
+
+module FormePDF
+  # Explicitly include this module in an ActionController; no Railtie or middleware.
+  module Rails
+    # 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)
+      html = render_to_string(template: template, layout: layout, locals: locals, formats: [:html])
+      FormePDF.render_html(html, **options)
+    end
+  end
+end

data/lib/forme_pdf/renderer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+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: [])
+      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)
+      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)}
+      })
+      Native.load!
+      input = FFI::MemoryPointer.from_string(html)
+      opts = FFI::MemoryPointer.from_string(options)
+      # Async interruption must not arrive between native allocation and ownership.
+      Thread.handle_interrupt(Object => :never) do
+        result = Native.forme_render_html(input, html.bytesize, opts, options.bytesize)
+        fail RenderError, "Native renderer returned no result" if result.null?
+        if Native.forme_result_status(result) != 0
+          fail RenderError, Native.copy(result, 2).force_encoding(Encoding::UTF_8)
+        end
+        pdf = Native.copy(result, 0)
+        metadata = JSON.parse(Native.copy(result, 1))
+        Result.new(pdf: pdf.freeze, warnings: metadata.fetch("warnings").map(&:freeze).freeze, passes: metadata.fetch("passes"))
+      ensure
+        Native.forme_result_destroy(result) if result && !result.null?
+      end
+    end
+  end
+end

data/lib/forme_pdf/result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FormePDF
+  Result = Data.define(:pdf, :warnings, :passes)
+end

data/lib/forme_pdf/version.rb

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

data/lib/forme_pdf.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "forme_pdf/version"
+require_relative "forme_pdf/errors"
+require_relative "forme_pdf/result"
+require_relative "forme_pdf/native"
+require_relative "forme_pdf/renderer"
+
+module FormePDF
+  # Render HTML to a binary PDF String.
+  def self.render_html(html, **options)
+    render_html_result(html, **options).pdf
+  end
+
+  # Render HTML and preserve diagnostics.
+  def self.render_html_result(html, **options)
+    Renderer.call(html, **options)
+  end
+
+  # Validate the gem-owned native library eagerly, e.g. at application startup.
+  def self.verify!
+    Native.load!
+    true
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: forme-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ajaya Agrawalla
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-09-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Independent Ruby bindings for the Rust Forme HTML renderer. No browser,
+  Node.js, WebAssembly or separate rendering service.
+email:
+- ajaya@clearstack.io
+executables: []
+extensions:
+- ext/forme_pdf/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE
+- NOTICE
+- README.md
+- SECURITY.md
+- THIRD_PARTY_LICENSES.txt
+- docs/README.md
+- docs/github-setup.md
+- docs/installation.md
+- docs/rails.md
+- docs/releasing.md
+- docs/rendering.md
+- docs/security-exceptions.md
+- examples/hello.rb
+- ext/forme_pdf/Cargo.lock
+- ext/forme_pdf/Cargo.toml
+- ext/forme_pdf/extconf.rb
+- ext/forme_pdf/src/lib.rs
+- lib/forme_pdf.rb
+- lib/forme_pdf/errors.rb
+- lib/forme_pdf/native.rb
+- lib/forme_pdf/rails.rb
+- lib/forme_pdf/renderer.rb
+- lib/forme_pdf/result.rb
+- lib/forme_pdf/version.rb
+homepage: https://github.com/clearstackio/forme-ruby
+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
+  bug_tracker_uri: https://github.com/clearstackio/forme-ruby/issues
+  changelog_uri: https://github.com/clearstackio/forme-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key: 
+specification_version: 4
+summary: Native HTML to PDF rendering for Ruby and Rails
+test_files: []