RubyGems - himg - Versions diffs - 0.0.3 → 0.0.5 - Mend

himg 0.0.3 → 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +20 -0
data/Cargo.lock +1 -1
data/README.md +54 -5
data/Rakefile +1 -1
data/ext/himg/Cargo.toml +1 -1
data/ext/himg/examples/file.rs +5 -3
data/ext/himg/src/html_to_image.rs +12 -6
data/ext/himg/src/lib.rs +34 -42
data/ext/himg/src/options.rs +2 -0
data/ext/himg/src/renderer.rs +32 -0
data/gemfiles/plain_ruby.gemfile.lock +1 -1
data/gemfiles/rails_6.gemfile.lock +1 -1
data/gemfiles/rails_7_0.gemfile.lock +1 -1
data/gemfiles/rails_7_1.gemfile.lock +1 -1
data/gemfiles/rails_7_2.gemfile.lock +1 -1
data/gemfiles/rails_8.gemfile.lock +1 -1
data/lib/himg/railtie/controller_config.rb +31 -0
data/lib/himg/railtie/template_handler.rb +2 -2
data/lib/himg/railtie.rb +13 -2
data/lib/himg/version.rb +1 -1
data/lib/himg.rb +5 -0
data/sig/himg.rbs +11 -3
metadata +3 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 286080c98560f491c524867c0986edd71e7e14bc912a50a2a72d627d4cb22e34
-  data.tar.gz: 435a08c13f0211d694ca477d4ce8a7afba24c686d088a7b7831c0397177d127c
+  metadata.gz: 1bd4c145135ae494ac36cefa1aade53d31d5314e54ce582126c76484115815f7
+  data.tar.gz: f631474fc095ea589af509e8c27e0386efb102868b225bad5be708d10e0b682a
 SHA512:
-  metadata.gz: d5ca027f7d92741dc71b872a5308a05228c9e7c7743ebcfd976175f3c4a5a0482d3831e0d3f664aa1a7870353e8d2d482c1e545b0fa558d802ca3131282323bd
-  data.tar.gz: e4a9e936a5d96a1574c9af213912bed55de8e25af94775007397a70a7bdebc9f5b41519fc35668738c0929e9f50821b18f1c58d0897f84443334fcba15b4973c
+  metadata.gz: c666c9444a47522f1843e34c3c065ee06e15d2995a5cbe0a537ab17acb96bfdb08414735c5c468ea47609169739f37bda38c4e74a745f12b643c45a1eaa1ded8
+  data.tar.gz: e629137b2de381bf1ed7f5cf5d6caa694372172056e9f1c7c80d6d879011641162ecf486863e51147349133ef1a2e189c13b13406d19bbd0971c9f3d9926d810

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,25 @@
 ## [Unreleased]
+## [0.0.5] - 2025-04-22
+- Can configure `render himg: ""` with options including `width:`, `height:`,
+  `truncate:` and `verbose:`.
+- Can use `himg_config` helper methods at controller level and action level
+  to set `@_himg_config`, which can then be passed to the renderer with
+  `render himg: "<!DOCTYPE html>", config: himg_config` as an alternative to
+  specifying config options individually to `ActionController::Rendering#render`.
+- `himg_config` helpers can also be used to control the configuration of
+  template based default render, when not calling render manually within the
+  controller. This works because the template handler can access `@_himg_config`.
+- Can use string width / height with Himg.render
+- Disable detailed log timings by default. Can re-enable with verbose: true.
+  There is still some logging from blitz-net#fetch for http requests and for
+  blitz-html::DocumentHtmlParser#finish on unexpected tokens.
+## [0.0.4] - 2025-04-22
+- Allow `width`, `height` and `truncate` to be passed to the render function.
 ## [0.0.3] - 2025-04-22
 - Ensure that when render height is expanded to fit the content that we update

data/Cargo.lock CHANGED Viewed

@@ -1065,7 +1065,7 @@ checksum = "dfa686283ad6dd069f105e5ab091b04c62850d3e4cf5d67debad1933f55023df"
 [[package]]
 name = "himg"
-version = "0.0.3"
+version = "0.0.5"
 dependencies = [
  "blitz-dom",
  "blitz-html",

data/README.md CHANGED Viewed

@@ -16,7 +16,6 @@ In Rails this will mean you can process user.himg.erb to display an image includ
 4. Network requests can be made: don't use this library with untrusted inputs.
 5. file:// URLs are resolved: this could expose files on your computer.
 6. Native extensions are not yet being published for different os/arch
-7. Verbose logging is hardcoded
 ## Installation
@@ -37,7 +36,13 @@ gem install himg
 ### Ruby
 ```ruby
-png = Himg.render("<html bgcolor='blue'></html>")
+png = Himg.render("<!DOCTYPE html><body style='background:blue;'></body>")
+File.open("blue.png", "wb"){|f| f.write(png) }
+```
+```ruby
+png = Himg.render("<!DOCTYPE html><h1>Snapshot</h1>", width: 89, height: 5, truncate: false)
+File.open("dynamic_height.png", "wb"){|f| f.write(png) }
 ```
 ### Rails
@@ -58,13 +63,46 @@ Once you've added a view template for your resource, you can use it to generate
 <meta property="og:image" content="<%= user_url(@user.username, format: :png) %>" />
 ```
-### Advanced Rails Usage
+### Configuration Options
+Options: `width`, `height`, `verbose`, `truncate`.
+### Passing options to a Rails view template
+Options can be set at a controller level using the `himg_config` helper method:
+```ruby
+class UsersController < ActionController::Base
+  himg_config(verbose: true)
+end
+```
+These can be overridden at a view level:
+```ruby
+class UsersController < ActionController::Base
+  def show
+    himg_config(width: params[:w]) if params[:w]
+    @user = User.new
+  end
+```
-A :himg template handler is registered and will be called by rails' `default_render` method automatically when the corresponding view is found. This can be `show.himg` for a static image, or `show.himg.erb` to use variables from the controller.
+### Rails manual render
 If you prefer you could also use `render himg: "<div>My Data</div>"` instead, but should be careful with untrusted input if constructing HTML manually.
-To be explicit in the controler you can also use `respond_to` style:
+Options can then be passed directly to the manual render:
+```ruby
+render himg: '<!DOCTYPE html>', truncate: false
+```
+Alternatively you can pass in options which have been set with `himg_config`:
+```ruby
+render himg: '<!DOCTYPE html>', config: himg_config
+```
+### Rails `respond_to`
+To be explicit in the controller you can also use `respond_to` style:
 ```ruby
 respond_to do |format|
@@ -73,6 +111,7 @@ respond_to do |format|
 end
 ```
+You can also use this combined with a manual render:
 ```ruby
 respond_to do |format|
   format.html
@@ -81,6 +120,16 @@ respond_to do |format|
 end
 ```
+### How it works
+No browser, just basics!
+Himg calls through to the amazing blitz library, which uses Stylo to parse the CSS, servo/html5ever to parse the HTML, fetches network resources, builds a scene graph and hands over to vello to render an image.
+Interaction between Ruby & Rust is done with the help of `magnus`, `rb_sys` and lots of glue code from the `oxidize-rb` team.
+To play nicely with Rails a template handler is registered, which Rails' `default_render` method automatically calls when the corresponding view is found. This can be `show.himg` for a static image, or `show.himg.erb` to use variables from the controller. Additionally a Renderer is available with `render himg: 'content'` in case a view template is not needed.
 ### Run directly from the command line to output an image
 ```bash

data/Rakefile CHANGED Viewed

@@ -20,7 +20,7 @@ RbSys::ExtensionTask.new("himg", GEMSPEC) do |ext|
 end
 require "bump/tasks"
-Bump.replace_in_default = %w[ext/himg/Cargo.toml]
+Bump.replace_in_default = %w[Cargo.lock ext/himg/Cargo.toml]
 Bump.changelog = :editor
 task default: %i[compile rubocop]

data/ext/himg/Cargo.toml CHANGED Viewed

@@ -1,7 +1,7 @@
 [package]
 name = "himg"
 description = "ruby bindings to expose a blitz html->png pipeline"
-version = "0.0.3"
+version = "0.0.5"
 edition = "2024"
 authors = ["James Edwards-Jones <git@jamedjo.co.uk>"]
 license = "MIT"

data/ext/himg/examples/file.rs CHANGED Viewed

@@ -21,7 +21,7 @@ async fn main() {
     // Fetch HTML from path
     let html = std::fs::read_to_string(&path_string).unwrap();
-    logger.log("Fetched HTML");
+    logger.log("Read HTML");
     // Configure viewport dimensions
     let options = Options {
@@ -30,20 +30,22 @@ async fn main() {
             height: 800,
             hidpi_scale: 1.0,
         },
+        truncate: false,
+        verbose: true,
         color_scheme: ColorScheme::Light,
         allow_net_requests: true, //TODO: Implement using this
     };
     // Render to Image
     let base_url = format!("file://{}", path_string.clone());
-    let buffer = html_to_image(&html, Some(base_url), options, &mut logger).await;
+    let render_output = html_to_image(&html, Some(base_url), options, &mut logger).await;
     // Determine output path, and open a file at that path.
     let out_path = compute_filename(&path_string);
     let mut file = File::create(&out_path).unwrap();
     // Encode buffer as PNG and write it to a file
-    write_png(&mut file, &buffer, options.image_size.scaled_width(), options.image_size.scaled_height()).unwrap();
+    write_png(&mut file, &render_output.buffer, render_output.image_size.scaled_width(), render_output.image_size.scaled_height()).unwrap();
     logger.log("Wrote out png");
     logger.log_total_time("\nDone");

data/ext/himg/src/html_to_image.rs CHANGED Viewed

@@ -64,15 +64,21 @@ pub async fn html_to_image(
     logger.log("Resolved styles and layout");
     // Determine height to render
-    let computed_height = document.as_ref().root_element().final_layout.size.height;
-    let render_height = (computed_height as u32).max(options.image_size.height).min(4000);
-    let render_size = ImageSize {
-        height: render_height,
-        ..options.image_size
+    let render_size = if options.truncate {
+        options.image_size
+    } else {
+        let computed_height = document.as_ref().root_element().final_layout.size.height;
+        let render_height = (computed_height as u32).max(options.image_size.height).min(10_000);
+        ImageSize {
+            height: render_height,
+            ..options.image_size
+        }
     };
     logger.log("Calculated render dimensions from document");
-    println!("Screenshot is ({}x{})",render_size.scaled_width(), render_size.scaled_height());
+    if options.verbose {
+        println!("Screenshot is ({}x{})",render_size.scaled_width(), render_size.scaled_height());
+    }
     // Render document to RGBA buffer
     let buffer = render_to_buffer(

data/ext/himg/src/lib.rs CHANGED Viewed

@@ -1,57 +1,49 @@
-pub mod writer;
-pub mod image_size;
+pub mod renderer;
 pub mod html_to_image;
-pub mod logger;
+pub mod image_size;
 pub mod options;
+pub mod writer;
+pub mod logger;
-pub use html_to_image::html_to_image;
+pub use renderer::render_blocking;
 pub use image_size::ImageSize;
 pub use options::Options;
+pub use html_to_image::html_to_image;
 pub use writer::write_png;
-pub use logger::{Logger, TimedLogger};
-use blitz_traits::{ColorScheme};
-use magnus::{function, prelude::*, ExceptionClass, Error, Ruby};
-pub fn render_blocking(html: String) -> Result<Vec<u8>, std::io::Error> {
-    let runtime = tokio::runtime::Runtime::new()?;
+use blitz_traits::ColorScheme;
+use magnus::{function, prelude::*, ExceptionClass, Error, Ruby, RString, RHash};
-    runtime.block_on(render(html))
-}
-// render_to_bytes, render_to_string, render_to_file, render_to_io
-pub async fn render(html: String) -> Result<Vec<u8>, std::io::Error> {
-    let mut logger = TimedLogger::init();
-    // Configure viewport dimensions
-    let options = Options {
-        image_size: ImageSize {
-            width: 720, //TODO: pass this in
-            height: 405, //TODO: decide if this will be fixed or dynamic from the document
-            hidpi_scale: 1.0,
-        },
-        color_scheme: ColorScheme::Light,
-        allow_net_requests: true, //TODO: Implement using this
-    };
-    // Render to Image
-    //let base_url = format!("file://{}", path_string.clone());
-    let base_url = None;
-    let render_output = html_to_image(&html, base_url, options, &mut logger).await;
-    // Determine output path, and open a file at that path.
-    let mut output_buffer: Vec<u8> = Vec::new();
-    // Encode buffer as PNG and write it to a file
-    write_png(&mut output_buffer, &render_output.buffer, render_output.image_size.scaled_width(), render_output.image_size.scaled_height())?;
+impl Options {
+    fn get_option<V: magnus::TryConvert + magnus::IntoValue>(optional_hash: Option<RHash>, key: &str, default: V) -> Result<V, Error> {
+        match optional_hash {
+            Some(hash) => hash.lookup2::<&str, V, V>(key, default),
+            None => Ok(default),
+        }
+    }
-    Ok(output_buffer)
+    pub fn from_ruby(hash: Option<RHash>) -> Result<Self, Error> {
+        let options = Options {
+            image_size: ImageSize {
+                width: Self::get_option(hash, "width", 720)?,
+                height: Self::get_option(hash, "height", 405)?,
+                hidpi_scale: 1.0,
+            },
+            truncate: Self::get_option(hash, "truncate", true)?,
+            verbose: Self::get_option(hash, "verbose", false)?,
+            color_scheme: ColorScheme::Light,
+            allow_net_requests: true, //TODO: Implement using this
+        };
+        Ok(options)
+    }
 }
-pub fn render_blocking_rb(ruby: &Ruby, html: String) -> Result<magnus::RString, magnus::Error> {
+pub fn render_blocking_rb(ruby: &Ruby, html: String, options: Option<RHash>) -> Result<RString, Error> {
+    let options = Options::from_ruby(options)?;
     let exception_class = ExceptionClass::from_value(magnus::eval("Himg::Error").unwrap()).unwrap();
-    match render_blocking(html) {
+    match render_blocking(html, options) {
         Ok(data) => Ok(ruby.str_from_slice(&data)),
         Err(e) => Err(Error::new(exception_class, format!("{}", e))),
     }
@@ -62,7 +54,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("Himg")?;
     //TODO: Allow optional base_url for resolving linked resources (stylesheets, images, fonts, etc)
-    module.define_singleton_method("render", function!(render_blocking_rb, 1))?;
+    module.define_singleton_method("render_to_string", function!(render_blocking_rb, 2))?;
     Ok(())
 }

data/ext/himg/src/options.rs CHANGED Viewed

@@ -7,4 +7,6 @@ pub struct Options {
     pub image_size: ImageSize,
     pub color_scheme: ColorScheme,
     pub allow_net_requests: bool,
+    pub truncate: bool,
+    pub verbose: bool,
 }

data/ext/himg/src/renderer.rs ADDED Viewed

@@ -0,0 +1,32 @@
+use crate::html_to_image::html_to_image;
+use crate::options::Options;
+use crate::writer::write_png;
+use crate::logger::{Logger, NullLogger, TimedLogger};
+pub fn render_blocking(html: String, options: Options) -> Result<Vec<u8>, std::io::Error> {
+    let runtime = tokio::runtime::Runtime::new()?;
+    runtime.block_on(render(html, options))
+}
+// render_to_bytes, render_to_string, render_to_file, render_to_io
+pub async fn render(html: String, options: Options) -> Result<Vec<u8>, std::io::Error> {
+    let mut logger: Box<dyn Logger> = if options.verbose {
+        Box::new(TimedLogger::init())
+    } else {
+        Box::new(NullLogger{})
+    };
+    // Render to Image
+    //let base_url = format!("file://{}", path_string.clone());
+    let base_url = None;
+    let render_output = html_to_image(&html, base_url, options, &mut *logger).await;
+    // Determine output path, and open a file at that path.
+    let mut output_buffer: Vec<u8> = Vec::new();
+    // Encode buffer as PNG and write it to a file
+    write_png(&mut output_buffer, &render_output.buffer, render_output.image_size.scaled_width(), render_output.image_size.scaled_height())?;
+    Ok(output_buffer)
+}

data/gemfiles/plain_ruby.gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    himg (0.0.2)
+    himg (0.0.4)
       rb_sys (~> 0.9)
 GEM

data/gemfiles/rails_6.gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    himg (0.0.2)
+    himg (0.0.4)
       rb_sys (~> 0.9)
 GEM

data/gemfiles/rails_7_0.gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    himg (0.0.2)
+    himg (0.0.4)
       rb_sys (~> 0.9)
 GEM

data/gemfiles/rails_7_1.gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    himg (0.0.2)
+    himg (0.0.4)
       rb_sys (~> 0.9)
 GEM

data/gemfiles/rails_7_2.gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    himg (0.0.2)
+    himg (0.0.4)
       rb_sys (~> 0.9)
 GEM

data/gemfiles/rails_8.gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    himg (0.0.2)
+    himg (0.0.4)
       rb_sys (~> 0.9)
 GEM

data/lib/himg/railtie/controller_config.rb ADDED Viewed

@@ -0,0 +1,31 @@
+module Himg
+  class Railtie
+    module ControllerConfig
+      extend ActiveSupport::Concern
+      included do
+        before_action :_apply_himg_config
+      end
+      class_methods do
+        def himg_config(options = {})
+          @_himg_global_config ||= {}
+          @_himg_global_config.merge!(options)
+        end
+        def _himg_global_config
+          @_himg_global_config&.dup || {}
+        end
+      end
+      def himg_config(options = {})
+        @_himg_config.merge!(options)
+        @_himg_config
+      end
+      def _apply_himg_config
+        @_himg_config = self.class._himg_global_config
+      end
+    end
+  end
+end

data/lib/himg/railtie/template_handler.rb CHANGED Viewed

@@ -4,7 +4,7 @@ module Himg
     class TemplateHandler
       def self.call(_template, source)
         <<-CODE
-          Himg.render(#{source.inspect})
+          Himg.render(#{source.inspect}, **@_himg_config)
         CODE
       end
     end
@@ -21,7 +21,7 @@ module Himg
           output = begin
             #{preprocessed_view_code}
           end
-          Himg.render(output)
+          Himg.render(output, **@_himg_config)
         CODE
       end
     end

data/lib/himg/railtie.rb CHANGED Viewed

@@ -29,10 +29,21 @@ module Himg
     end
     initializer "himg.controller_renderer" do
-      ActionController::Renderers.add :himg do |obj, _options|
-        png_data = Himg.render(obj)
+      ActionController::Renderers.add :himg do |obj, options = {}|
+        configured_options = options[:config] || {}
+        direct_options = options.symbolize_keys.slice(*Himg::RENDER_OPTIONS)
+        merged_options = configured_options.merge(direct_options)
+        png_data = Himg.render(obj, **merged_options)
         send_data png_data, type: "image/png", disposition: "inline"
       end
     end
+    initializer 'himg.controller_config' do
+      require "himg/railtie/controller_config"
+      ActiveSupport.on_load(:action_controller) do
+        include Himg::Railtie::ControllerConfig
+      end
+    end
   end
 end

data/lib/himg/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module Himg
-  VERSION = "0.0.3"
+  VERSION = "0.0.5"
 end

data/lib/himg.rb CHANGED Viewed

@@ -16,5 +16,10 @@ end
 #
 # Converts HTML to an Image for a minimal subset of HTML and CSS
 module Himg
+  RENDER_OPTIONS = %i[width height truncate verbose].freeze
   class Error < StandardError; end
+  def self.render(html, width: 720, height: 405, truncate: true, verbose: false)
+    render_to_string(html, "width" => width.to_i, "height" => height.to_i, "truncate" => truncate, "verbose" => verbose)
+  end
 end

data/sig/himg.rbs CHANGED Viewed

@@ -1,8 +1,16 @@
 module Himg
   VERSION: String
-  class Renderer
-    def initialize: (Integer width, Integer height) -> void
-    def render: (String html) -> String
+  class Error < StandardError
   end
+  def self.render: (
+    String html,
+    ?width: Integer,
+    ?height: Integer,
+    ?truncate: bool,
+    ?verbose: bool
+  ) -> String
+  def self.render_to_string: (String html, Hash[string, untyped] options) -> String
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: himg
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - James Edwards-Jones
@@ -180,6 +180,7 @@ files:
 - ext/himg/src/lib.rs
 - ext/himg/src/logger.rs
 - ext/himg/src/options.rs
+- ext/himg/src/renderer.rs
 - ext/himg/src/writer.rs
 - gemfiles/plain_ruby.gemfile
 - gemfiles/plain_ruby.gemfile.lock
@@ -195,6 +196,7 @@ files:
 - gemfiles/rails_8.gemfile.lock
 - lib/himg.rb
 - lib/himg/railtie.rb
+- lib/himg/railtie/controller_config.rb
 - lib/himg/railtie/template_handler.rb
 - lib/himg/version.rb
 - sig/himg.rbs