oicana 0.10.0.rc.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 662a0cf75e712bac0ebaa8c29e469b3ec493c30538b5a8a2e00f2d874891c5a4
+  data.tar.gz: 4232490425ad9ab79340f413fba01adb28087d523c9e7284f1e6c29d3ec5ad91
+SHA512:
+  metadata.gz: 15549c67a07e494f283b99f89688a04131fac6d8f789b640eec0ee6038c6fd5c79d4b9f2a42315f1c60958d02c00d0d8498d8b900a784904de6724335dfb7fa9
+  data.tar.gz: 0a7d2dcb343c1ba1409b94408177f21820ac7b4e662e212e326eaefe70ed83a06db32520c14f8cca7b94e2943b38364c670fa4e0b74f5dca6534efaf4ad152af

data/LICENSE.md

@@ -0,0 +1,131 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

data/README.md

@@ -0,0 +1,40 @@
+# Oicana for Ruby
+
+*Generate PDFs in Ruby without a headless browser.*
+
+Ruby apps generating PDFs usually wrap the abandoned wkhtmltopdf through wicked_pdf or PDFKit, drive headless Chrome through Grover, or write every layout as code with Prawn.
+
+Oicana compiles PDFs in process through a native library instead. You design documents as [Typst](https://typst.app/) templates, load them once at startup, and render them from JSON in single-digit milliseconds. No browser process, no per-document fees, no document data leaving your infrastructure.
+
+> **Free for noncommercial use.** Commercial use is free for 30 days, then needs a [per-application subscription](https://oicana.com/#pricing) with unlimited seats.
+
+## Installation
+
+```bash
+gem install oicana     # or: bundle add oicana
+```
+
+Requires Ruby 3.2 or newer. Platform gems bring the native library for Linux (x64 and arm64, glibc 2.28 or newer, or musl), macOS (x64 and arm64), and Windows (x64 and arm64).
+
+## Quick start
+
+```ruby
+require "oicana"
+
+template = Oicana::Template.new(File.binread("invoice-0.1.0.zip"))
+
+pdf = template.export_pdf(
+  json_inputs: { "invoice" => { number: "2026-001", customer: "Acme GmbH", total: "€1,190.00" } }
+)
+File.binwrite("invoice.pdf", pdf)
+```
+
+JSON inputs take Strings holding JSON, or any value `JSON.generate` accepts. Blob inputs take binary Strings or `Oicana::BlobInput` values with metadata. `export_png` and `export_svg` produce the other formats, `pages:` takes a page index or a Range, `compile` keeps a document to export its pages separately, and `Template.export_once` renders a template once without caching it. Errors are subclasses of `Oicana::Error`.
+
+## Running in a web service
+
+Creating a `Template` compiles it once to warm up the Typst cache, so create it once per process, not per request. Oicana cannot compile in a process forked after its parent compiled, so with forking servers and job runners like Puma in cluster mode or Solid Queue, create templates on first use instead of during boot. A template is safe to use from multiple threads, and native calls release the GVL. Templates and compiled documents are freed by the garbage collector, or right away with `close`.
+
+## Licensing
+
+Oicana is source-available under the [PolyForm Noncommercial License 1.0.0](https://github.com/oicana/oicana/blob/main/LICENSE.md) and free for noncommercial use. Commercial use is free for 30 days; see [pricing](https://oicana.com/#pricing) for subscriptions, or write to `hello@oicana.com`.

data/lib/oicana/errors.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Oicana
+  # Base class of all errors raised by Oicana. The message includes rendered
+  # compilation diagnostics.
+  class Error < StandardError; end
+
+  # The packed template could not be read or its manifest is invalid.
+  class InvalidTemplateError < Error; end
+
+  # An input value, its blob metadata, or a page range is invalid.
+  class InvalidInputError < Error; end
+
+  # The template failed to compile.
+  class CompilationError < Error; end
+
+  # The requested file is not part of the template.
+  class FileNotFoundError < Error; end
+
+  # The compiled document could not be exported.
+  class ExportError < Error; end
+
+  # A template or document is no longer registered.
+  class NotFoundError < Error; end
+
+  # An unexpected failure inside Oicana.
+  class InternalError < Error; end
+
+  # A template or document was used after #close.
+  class ClosedError < Error; end
+
+  ERRORS = {
+    "InvalidTemplate" => InvalidTemplateError,
+    "InvalidInput" => InvalidInputError,
+    "Compilation" => CompilationError,
+    "FileNotFound" => FileNotFoundError,
+    "Export" => ExportError,
+    "NotFound" => NotFoundError,
+    "Internal" => InternalError
+  }.freeze
+  private_constant :ERRORS
+
+  @compiling_pid = nil
+
+  # @api private
+  # Runs the block and translates errors of the generated bindings.
+  def self.translate_errors
+    if @compiling_pid && @compiling_pid != Process.pid
+      raise Error, "Oicana cannot be used in a forked process after the parent process #{@compiling_pid} " \
+                   "used it. Create templates after forking, for example lazily on first use."
+    end
+    @compiling_pid = Process.pid
+    yield
+  rescue OicanaUniffi::OicanaError::InvalidTemplate, OicanaUniffi::OicanaError::InvalidInput,
+         OicanaUniffi::OicanaError::Compilation, OicanaUniffi::OicanaError::FileNotFound,
+         OicanaUniffi::OicanaError::Export, OicanaUniffi::OicanaError::NotFound,
+         OicanaUniffi::OicanaError::Internal => e
+    raise ERRORS.fetch(e.class.name.split("::").last), e.message
+  rescue OicanaUniffi::InternalError => e
+    raise InternalError, e.message
+  end
+end

data/lib/oicana/native.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Oicana
+  # Loads the native library and adjusts the generated bindings in lib/oicana/oicana_uniffi.rb.
+  module Native
+    # Makes every native call release the GVL, so other Ruby threads keep running while
+    # a template compiles or exports.
+    module BlockingCalls
+      def attach_function(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        super(*args, options.merge(blocking: true))
+      end
+    end
+
+    # Copies strings into native buffers at once. The generated code goes through
+    # String#bytes, which allocates an Integer for every byte.
+    module BulkWrites
+      def write(value)
+        reserve(value.bytesize) do
+          @rust_buf.data.put_bytes(@rust_buf.len, value)
+        end
+      end
+
+      def write_String(value)
+        value = OicanaUniffi.uniffi_utf8(value)
+        pack_into 4, "l>", value.bytesize
+        write value
+      end
+
+      def write_Bytes(value)
+        value = OicanaUniffi.uniffi_bytes(value)
+        pack_into 4, "l>", value.bytesize
+        write value
+      end
+    end
+
+    # The native library, either from OICANA_LIBRARY_PATH or shipped in the platform gem.
+    def self.library_path
+      ENV.fetch("OICANA_LIBRARY_PATH") do
+        path = File.expand_path("native/#{FFI.map_library_name("oicana_uniffi")}", __dir__)
+        return path if File.exist?(path)
+
+        raise LoadError, missing_library_message
+      end
+    end
+
+    def self.missing_library_message
+      platform = Gem::Platform.local
+      if %w[x86_64 x64 aarch64 arm64].include?(platform.cpu) && %w[linux darwin mingw].include?(platform.os)
+        "The oicana gem without a native library is installed, but #{platform} has a platform gem that " \
+          "contains it. Check that Bundler's force_ruby_platform is not set, and add the platform to your " \
+          "Gemfile.lock with `bundle lock --add-platform #{platform}`."
+      else
+        "Oicana has no native library for #{platform}. Supported are Linux (glibc and musl), macOS and " \
+          "Windows, each on x64 and arm64. Set OICANA_LIBRARY_PATH to use a library built from source."
+      end
+    end
+
+    # Called by the generated bindings, see uniffi.toml.
+    def self.prepare(library)
+      library.singleton_class.prepend(BlockingCalls)
+      library_path
+    end
+
+    def self.patch_bindings
+      OicanaUniffi.const_get(:RustBufferBuilder).prepend(BulkWrites)
+    end
+  end
+end