himg 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 516bc67aa868ad60941f30c3da0ae3394c52527d98066260ec6eccbf7c37d71c
-  data.tar.gz: e2b6109e2d740755aca950d0615de4e45cb2d3d988c323d32425b3bd835f8378
+  metadata.gz: 286080c98560f491c524867c0986edd71e7e14bc912a50a2a72d627d4cb22e34
+  data.tar.gz: 435a08c13f0211d694ca477d4ce8a7afba24c686d088a7b7831c0397177d127c
 SHA512:
-  metadata.gz: 3eedcbb8954b86e31808c6a4cfb13b76db86086c7c243babd9ecf244cc0d0bb8d6b0dab174b06f6d79420d1eb75ee58e6e3c1f9ca0694b08ded2c8a5a2283c92
-  data.tar.gz: f7f2c9c1b9e9731a9c7baff46b5307508e37c9204a232b55b29f9f1dda69cd2ae66ddcc51d91936689c716a0be1f89396388cbcffaf2914d3b264e02a78f19eb
+  metadata.gz: d5ca027f7d92741dc71b872a5308a05228c9e7c7743ebcfd976175f3c4a5a0482d3831e0d3f664aa1a7870353e8d2d482c1e545b0fa558d802ca3131282323bd
+  data.tar.gz: e4a9e936a5d96a1574c9af213912bed55de8e25af94775007397a70a7bdebc9f5b41519fc35668738c0929e9f50821b18f1c58d0897f84443334fcba15b4973c

data/.rubocop.yml

@@ -0,0 +1,20 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  Enabled: false

data/Appraisals

@@ -0,0 +1,40 @@
+appraise "plain-ruby" do
+  remove_gem "rails"
+  remove_gem "puma"
+end
+
+appraise "rails-6" do
+  remove_gem "puma"
+  gem "rails", "~> 6.0"
+  gem "rspec-rails", "~> 6.0"
+  gem "concurrent-ruby", "1.3.4" # Logger dependency fix, see: https://stackoverflow.com/questions/79360526/uninitialized-constant-activesupportloggerthreadsafelevellogger-nameerror
+  gem "bigdecimal", "~> 1.4" # See: https://github.com/rails/rails/issues/34822
+  gem "drb"
+end
+
+appraise "rails-7-0" do
+  remove_gem "puma"
+  gem "rails", "~> 7.0.0"
+  gem "rspec-rails", "~> 7.0"
+  gem "concurrent-ruby", "1.3.4" # Logger dependency fix, see: https://stackoverflow.com/questions/79360526/uninitialized-constant-activesupportloggerthreadsafelevellogger-nameerror
+  gem "bigdecimal", "~> 1.4" # See: https://github.com/rails/rails/issues/34822
+  gem "drb"
+end
+
+appraise "rails-7-1" do
+  remove_gem "puma"
+  gem "rails", "~> 7.1.0"
+  gem "rspec-rails", "~> 7.0"
+end
+
+appraise "rails-7-2" do
+  remove_gem "puma"
+  gem "rails", "~> 7.2.0"
+  gem "rspec-rails", "~> 7.0"
+end
+
+appraise "rails-8" do
+  remove_gem "puma"
+  gem "rails", "~> 8.0"
+  gem "rspec-rails", "~> 7.0"
+end

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.0.3] - 2025-04-22
+
+- Ensure that when render height is expanded to fit the content that we update
+  the height we try to write in the png metadata to match.
+- Rust creates a ruby string with the binary png data so we don't need to convert with .pack("C*")
+- Himg::Error wraps errors from a Rust Result<_,Err>
+- Added OpenGraph metadata example
+- Default dimensions of 720x405 to match the ideal 16:9 ratio and image size
+  for sharing og-image on messengers and social media.
+
+## [0.0.2] - 2025-04-21
+
+- Adds Rails support via a ActionView template handler.
+  Takes views like `action.show.erb`, pre-processes them with Erb and renders
+  to a .png with 'image/png' set as the MIME type.
+- Adds a `ActionController::Renderer` so `render himg: '<div>Some HTML</div>'`
+  can be used either directly or from a `format.png`/`format.himg` block.
+
 ## [0.0.1] - 2025-04-19
 
 - Initial alpha

data/Cargo.lock

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

data/README.md

@@ -1,6 +1,6 @@
-# Himg
+# Himg: The Hyper Image Generator
 
-Library for generating an image from HTML
+You give it HTML and it gives back an image!
 
 Parses a minimal subset of HTML/CSS, fetches nested resources, renders an image on the GPU.
 
@@ -8,31 +8,81 @@ Uses rust libraries to do this in a fast, hopefully safe way.
 
 In Rails this will mean you can process user.himg.erb to display an image including data from a user's profile.
 
-## Installation
+## CAVEATS
+
+1. This is **pre-alpha** software, don't expect it to work yet.
+2. Rendering requires a GPU. Awaiting CPU support in vello, which Canva may be working on.
+3. Performance needs tuning. Both in the underlying blitz library and how data is passed between Rust and Ruby
+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
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add himg
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install himg
 ```
 
 ## Usage
 
-### Run from Ruby
+### Ruby
 
 ```ruby
 png = Himg.render("<html bgcolor='blue'></html>") 
 ```
 
+### Rails
+
+Simply add a `show.himg.erb`!
+
+```erb
+<div><%= @username %></div>
+```
+
+### Adding OpenGraph Meta Tags
+
+Once you've added a view template for your resource, you can use it to generate image cards that will be shown when the page is shared on messenger apps or social media.
+
+```html
+<meta property="og:title" content="<%= @user.username %>" />
+<meta property="og:description" content="<%= @user.tagline %>" />
+<meta property="og:image" content="<%= user_url(@user.username, format: :png) %>" />
+```
+
+### Advanced Rails Usage
+
+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.
+
+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:
+
+```ruby
+respond_to do |format|
+  format.html
+  format.himg
+end
+```
+
+```ruby
+respond_to do |format|
+  format.html
+  format.himg { render himg: '<h1 style="text-align: center;">Recent Users</h1>' }
+  format.png { render himg: '<div>For .png URLs</div>' }
+end
+```
+
 ### Run directly from the command line to output an image
+
 ```bash
 bundle exec cargo run --example file
 bundle exec cargo run --example file -- path/to/file.html
@@ -40,9 +90,21 @@ bundle exec cargo run --example file -- path/to/file.html
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+1. Run `bin/setup` to install dependencies.
+2. Run `rake spec` to run the tests with the default development setup
+3. Run `appraisal rake spec` to run tests against different versions of rails and to confirm that the gem works in a plain ruby environment
+4. Run `bin/console` for an interactive prompt that will allow you to experiment.
+5. Run `RAILS_ENV=development bundle exec spec/dummy/dummy_rails server` to check the dummy app.
+  - http://localhost:3000/users/jamedjo.png will display an opengraph compatible png
+  - http://localhost:3000/users/jamedjo.himg will also render the same png
+  - http://localhost:3000/users/jamedjo will render an HTML page with opengraph meta tags
+6. To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Releases
+
+To release a new version:
+1. Run `rake bump:patch` to update the version numbers in `version.rb` and `ext/himg/Cargo.toml`.
+3. Run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/Rakefile

@@ -5,7 +5,9 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "standard/rake"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
 
 require "rb_sys/extensiontask"
 
@@ -17,4 +19,8 @@ RbSys::ExtensionTask.new("himg", GEMSPEC) do |ext|
   ext.lib_dir = "lib/himg"
 end
 
-task default: %i[compile spec standard]
+require "bump/tasks"
+Bump.replace_in_default = %w[ext/himg/Cargo.toml]
+Bump.changelog = :editor
+
+task default: %i[compile rubocop]

data/Steepfile

@@ -17,13 +17,3 @@ target :lib do
   #   hash[D::Ruby::NoMethod] = :information
   # end
 end
-
-#target :test do
-#  unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
-#  signature "sig/test"              # Put RBS files for tests under `sig/test`
-#  check "test"                      # Type check Ruby scripts under `test`
-
-#  configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
-
-#  # library "pathname"              # Standard libraries
-#end

data/ext/himg/Cargo.toml

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

data/ext/himg/examples/file.rs

@@ -43,7 +43,7 @@ async fn main() {
     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());
+    write_png(&mut file, &buffer, options.image_size.scaled_width(), options.image_size.scaled_height()).unwrap();
     logger.log("Wrote out png");
 
     logger.log_total_time("\nDone");

data/ext/himg/src/html_to_image.rs

@@ -11,12 +11,17 @@ use crate::image_size::ImageSize;
 use crate::logger::Logger;
 use crate::options::Options;
 
+pub struct RenderOutput {
+    pub buffer: Vec<u8>,
+    pub image_size: ImageSize,
+}
+
 pub async fn html_to_image(
     html: &str,
     base_url: Option<String>,
     options: Options,
     logger: &mut dyn Logger,
-) -> Vec<u8> {
+) -> RenderOutput {
     let (mut recv, callback) = MpscCallback::new();
     logger.log("Initial config");
 
@@ -83,5 +88,8 @@ pub async fn html_to_image(
 
     logger.log("Rendered to buffer");
 
-    buffer
+    RenderOutput {
+        buffer: buffer,
+        image_size: render_size,
+    }
 }

data/ext/himg/src/lib.rs

@@ -11,22 +11,23 @@ pub use writer::write_png;
 pub use logger::{Logger, TimedLogger};
 
 use blitz_traits::{ColorScheme};
-use magnus::{function, prelude::*, Error, Ruby};
+use magnus::{function, prelude::*, ExceptionClass, Error, Ruby};
 
-pub fn render_blocking(html: String) -> Vec<u8> {
-    tokio::runtime::Runtime::new()
-        .unwrap()
-        .block_on(render(html))
+pub fn render_blocking(html: String) -> Result<Vec<u8>, std::io::Error> {
+    let runtime = tokio::runtime::Runtime::new()?;
+
+    runtime.block_on(render(html))
 }
 
-pub async fn render(html: String) -> Vec<u8> {
+// 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: 1200, //TODO: pass this in
-            height: 800, //TODO: decide if this will be fixed or dynamic from the document
+            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,
@@ -36,15 +37,24 @@ pub async fn render(html: String) -> Vec<u8> {
     // Render to Image
     //let base_url = format!("file://{}", path_string.clone());
     let base_url = None;
-    let image_data = html_to_image(&html, base_url, options, &mut logger).await;
+    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, &image_data, options.image_size.scaled_width(), options.image_size.scaled_height());
+    write_png(&mut output_buffer, &render_output.buffer, render_output.image_size.scaled_width(), render_output.image_size.scaled_height())?;
+
+    Ok(output_buffer)
+}
 
-    output_buffer
+pub fn render_blocking_rb(ruby: &Ruby, html: String) -> Result<magnus::RString, magnus::Error> {
+    let exception_class = ExceptionClass::from_value(magnus::eval("Himg::Error").unwrap()).unwrap();
+
+    match render_blocking(html) {
+        Ok(data) => Ok(ruby.str_from_slice(&data)),
+        Err(e) => Err(Error::new(exception_class, format!("{}", e))),
+    }
 }
 
 #[magnus::init]
@@ -52,7 +62,8 @@ 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, 1))?;
+    module.define_singleton_method("render", function!(render_blocking_rb, 1))?;
+
     Ok(())
 }
 

data/ext/himg/src/writer.rs

@@ -4,9 +4,9 @@ use png::{Encoder, ColorType, BitDepth, PixelDimensions, Unit};
 const INCHES_PER_METER: f64 = 39.3701;
 const DEFAULT_DPI: f64 = 144.0;
 
-pub fn write_png<W: Write>(writer: W, buffer: &[u8], width: u32, height: u32) {
+pub fn write_png<W: Write>(writer: W, buffer: &[u8], width: u32, height: u32) -> Result<(), std::io::Error> {
     let encoder = create_encoder(writer, width, height, DEFAULT_DPI);
-    write_data(encoder, buffer);
+    write_data(encoder, buffer)
 }
 
 fn create_encoder<'a, W: Write>(writer: W, width: u32, height: u32, dpi: f64) -> Encoder<'a, W> {
@@ -24,10 +24,11 @@ fn create_encoder<'a, W: Write>(writer: W, width: u32, height: u32, dpi: f64) ->
     encoder
 }
 
-fn write_data<W: Write>(encoder: Encoder<W>, buffer: &[u8]) {
-    //TODO: Better error handling instead of unwrap
-    let mut writer = encoder.write_header().unwrap();
+fn write_data<W: Write>(encoder: Encoder<W>, buffer: &[u8]) -> Result<(), std::io::Error> {
+    let mut writer = encoder.write_header()?;
 
-    writer.write_image_data(buffer).unwrap();
-    writer.finish().unwrap();
+    writer.write_image_data(buffer)?;
+    writer.finish()?;
+
+    Ok(())
 }

data/gemfiles/plain_ruby.gemfile

@@ -0,0 +1,5 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gemspec path: "../"

data/gemfiles/plain_ruby.gemfile.lock

@@ -0,0 +1,181 @@
+PATH
+  remote: ..
+  specs:
+    himg (0.0.2)
+      rb_sys (~> 0.9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.0.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    appraisal (2.5.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.3)
+    base64 (0.2.0)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    bump (0.10.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.1)
+    csv (3.3.4)
+    date (3.4.1)
+    debug (1.10.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.1)
+    drb (2.2.1)
+    ffi (1.17.2)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86-linux-musl)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    fileutils (1.7.3)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.10.2)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    minitest (5.25.5)
+    mutex_m (0.3.0)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.3)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rake-compiler (1.3.0)
+      rake
+    rake-compiler-dock (1.9.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rb_sys (0.9.111)
+      rake-compiler-dock (= 1.9.1)
+    rbs (3.9.2)
+      logger
+    rdoc (6.13.1)
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.3)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.2)
+    rubocop (1.75.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    steep (1.10.0)
+      activesupport (>= 5.1)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.17.0.4, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      mutex_m (>= 0.3.0)
+      parser (>= 3.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (~> 3.9)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 5)
+      uri (>= 0.12.0)
+    stringio (3.1.7)
+    strscan (3.1.3)
+    terminal-table (4.0.0)
+      unicode-display_width (>= 1.1.1, < 4)
+    thor (1.3.2)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    uri (1.0.3)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  appraisal
+  bump
+  debug
+  himg!
+  irb
+  rake
+  rake-compiler
+  rspec
+  rubocop
+  steep
+
+BUNDLED WITH
+   2.6.7

data/gemfiles/rails_6.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "~> 6.0"
+gem "rspec-rails", "~> 6.0"
+gem "concurrent-ruby", "1.3.4"
+gem "bigdecimal", "~> 1.4"
+gem "drb"
+
+gemspec path: "../"