shojiku 0.1.0

data/lib/shojiku/config.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Process-wide configuration: the {Shojiku::Config} object and the
+# module-level entry points that reach it.
+module Shojiku
+  # Process-wide defaults for every {Client} built after it is set.
+  #
+  # The ecosystem idiom (a `configure` block in an initializer) OVER the
+  # frozen constructor, never a third precedence layer: what `configure` sets
+  # stands exactly where an explicit constructor argument stands against the
+  # environment. So the order is
+  #
+  #   explicit argument > `Shojiku.configure` > `SHOJIKU_*`
+  #
+  # for the template root and the pack directories, and the deliberate
+  # reverse for the engine library — `SHOJIKU_LIBRARY` still wins over both,
+  # because where the engine lives is a deployment decision.
+  #
+  # **`strict` is the one exception, and it is the only place `configure`
+  # beats a call site.** Strictness is a restriction rather than a default: an
+  # operator who declared a lockdown must not have it lifted by application
+  # code passing `strict: false`. Every SDK mirrors that asymmetry.
+  #
+  # The rule the other six mirror: an ecosystem-standard configuration idiom
+  # (an options object, properties, a builder) feeds the same constructor and
+  # never adds a precedence level of its own.
+  class Config
+    # Every setting a client can take, which is also what {#merge} accepts —
+    # so a misspelled key is a named error rather than a silently ignored one.
+    ATTRIBUTES = %i[
+      templates font_dirs locale_dirs lang library logger strict providers env
+    ].freeze
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize
+      @strict = false
+      @providers = {}
+      @env = true
+    end
+
+    # A copy with `overrides` applied — one client's resolution step.
+    #
+    # A nil override means "not given", so an explicit constructor argument
+    # beats a configured default and an absent one inherits it. `strict` is
+    # the exception documented above: it is OR-ed rather than overridden.
+    #
+    # `providers` replaces rather than merges. A client that declares its own
+    # registry is stating the whole set it may sign with, and quietly adding
+    # globally-registered keys to that set would defeat the point.
+    def merge(overrides)
+      merged = dup
+      overrides.each do |key, value|
+        raise UsageError, "unknown client setting `#{Echo.bounded(key)}`" unless
+          ATTRIBUTES.include?(key)
+
+        merged.public_send(:"#{key}=", value) unless value.nil?
+      end
+      merged.strict = strict || merged.strict
+      merged
+    end
+  end
+
+  class << self
+    # The process-wide defaults. Mutated through {configure}, read by every
+    # {Client} at construction.
+    def config
+      @config ||= Config.new
+    end
+
+    # ```ruby
+    # Shojiku.configure do |config|
+    #   config.templates = "app/templates"
+    #   config.lang = "ja-JP"
+    # end
+    # ```
+    def configure
+      yield(config)
+      config
+    end
+
+    # Drops every configured default.
+    #
+    # Public because a global that cannot be reset makes every test suite
+    # invent its own teardown — and get it wrong in a randomly-ordered run.
+    # Applications call it at most once, if at all.
+    def reset_configuration!
+      @config = Config.new
+    end
+  end
+end

data/lib/shojiku/diagnostic.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # One thing the engine noticed about a document.
+  #
+  # Passed through, never interpreted. `code` and `args` are the engine's
+  # frozen contract — a translating consumer renders its own message from
+  # them — so this class parses the wire and stops. It does not translate, it
+  # does not re-classify, and it never becomes an exception: a render that
+  # warns still succeeded, and a render that failed says why in these.
+  class Diagnostic
+    attr_reader :severity, :code, :category, :message, :path, :args, :origin
+
+    def self.parse(json)
+      return [] if json.nil? || json.empty?
+
+      items = JSON.parse(json)["items"]
+      Array(items).map { |item| new(item) }
+    end
+
+    def initialize(item)
+      @severity = item["severity"]
+      @code = item["code"]
+      @category = item["category"]
+      @message = item["message"]
+      @path = item["path"]
+      @args = item["args"] || {}
+      @origin = item["origin"]
+    end
+
+    def error?
+      @severity == "error"
+    end
+
+    def warning?
+      @severity == "warning"
+    end
+
+    def to_s
+      [@path, @message].compact.join(": ")
+    end
+  end
+end

data/lib/shojiku/engine.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+module Shojiku
+  # Everything copied out of one result handle, before that handle is freed.
+  #
+  # A snapshot rather than a wrapper, and that is the ownership rule of this
+  # binding in one word: no Ruby object ever holds a pointer into engine
+  # memory. The accessors LEND — their pointers die with the handle — so the
+  # bytes are copied while the handle is alive and the handle is freed on the
+  # way out, on every path.
+  Snapshot = Data.define(:status, :success, :pdf, :json, :diagnostics, :error)
+
+  # The declared C surface, and the one place a call crosses into it.
+  #
+  # Every function is declared with explicit argument and return types.
+  # Fiddle's default return type is a C `int`, which truncates every pointer
+  # this library hands back — a segfault that looks like a memory bug and is
+  # really a missing declaration.
+  class Engine
+    VOIDP = Fiddle::TYPE_VOIDP
+    SIZE_T = Fiddle::TYPE_SIZE_T
+    INT = Fiddle::TYPE_INT
+    VOID = Fiddle::TYPE_VOID
+
+    # Unpack directives that match the C types EXACTLY, rather than Ruby's
+    # native-width shorthands. `l!` is a native `long`, which is 8 bytes where
+    # `int32_t` is 4 — and `unpack1` on a buffer shorter than its directive
+    # returns nil rather than raising, so every flag would silently read as
+    # false. `l` is int32 and these two are picked from the real `size_t`
+    # width, which differs from `unsigned long` on Windows.
+    INT32 = "l"
+    SIZE = Fiddle::SIZEOF_SIZE_T == 8 ? "Q" : "L"
+
+    # Only the lifecycle the SDK contract defines is bound: engine info,
+    # render, sign, verify. `validate` and `preview` are the authoring
+    # surface's, not an artifact lifecycle's — the Designer reaches them
+    # through the WASM bindings, and binding them here would be surface with
+    # no contract behind it.
+    def initialize(library)
+      @library = library
+      @info = library.function(:shojiku_engine_info, [VOIDP], INT)
+      @render = library.function(:shojiku_render, [VOIDP, SIZE_T, VOIDP], INT)
+      @sign = library.function(
+        :shojiku_sign,
+        [VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP], INT
+      )
+      @verify = library.function(:shojiku_verify, [VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP], INT)
+      declare_accessors(library)
+    end
+
+    def engine_info
+      invoke { |out| @info.call(out) }
+    end
+
+    def render(request)
+      invoke { |out| @render.call(request, request.bytesize, out) }
+    end
+
+    def sign(pdf:, key:, certificate:, passphrase: nil)
+      invoke do |out|
+        @sign.call(
+          pdf, pdf.bytesize, key, key.bytesize, certificate, certificate.bytesize,
+          passphrase, passphrase ? passphrase.bytesize : 0, out
+        )
+      end
+    end
+
+    def verify(pdf:, anchors:)
+      invoke { |out| @verify.call(pdf, pdf.bytesize, anchors, anchors.bytesize, out) }
+    end
+
+    private
+
+    def declare_accessors(library)
+      buffers = %i[shojiku_result_pdf shojiku_result_json shojiku_result_diagnostics_json
+                   shojiku_result_error_json]
+      @buffers = buffers.to_h { |name| [name, library.function(name, [VOIDP] * 3, INT)] }
+      @success = library.function(:shojiku_result_success, [VOIDP, VOIDP], INT)
+      @free = library.function(:shojiku_result_free, [VOIDP], VOID)
+    end
+
+    # Runs one operation and copies its result out.
+    #
+    # The `ensure` is the ownership contract: exactly one handle crosses and
+    # exactly one free pairs with it, whatever happens in between.
+    def invoke
+      out = zeroed(Fiddle::SIZEOF_VOIDP)
+      status = yield(out)
+      handle = out.ptr
+      begin
+        snapshot(status, handle)
+      ensure
+        @free.call(handle)
+      end
+    end
+
+    def snapshot(status, handle)
+      Snapshot.new(
+        status: status,
+        success: succeeded?(handle),
+        pdf: buffer(handle, :shojiku_result_pdf),
+        json: text(handle, :shojiku_result_json),
+        diagnostics: text(handle, :shojiku_result_diagnostics_json),
+        error: text(handle, :shojiku_result_error_json)
+      )
+    end
+
+    def succeeded?(handle)
+      slot = zeroed(Fiddle::SIZEOF_INT)
+      @success.call(handle, slot)
+      slot[0, Fiddle::SIZEOF_INT].unpack1(INT32) == 1
+    end
+
+    # Copies what an accessor lent. `to_str` copies, which is the whole point:
+    # the pointer it copies from stops being valid the moment the handle is
+    # freed, a few lines later.
+    def buffer(handle, name)
+      pointer = zeroed(Fiddle::SIZEOF_VOIDP)
+      length = zeroed(Fiddle::SIZEOF_SIZE_T)
+      @buffers.fetch(name).call(handle, pointer, length)
+      size = length[0, Fiddle::SIZEOF_SIZE_T].unpack1(SIZE)
+      size.zero? ? (+"").b : pointer.ptr.to_str(size)
+    end
+
+    # The same, for a buffer the surface guarantees is UTF-8. The encoding is
+    # forced rather than inherited: a platform default would differ on
+    # Windows, which is a first-class target here.
+    def text(handle, name)
+      buffer(handle, name).force_encoding(Encoding::UTF_8)
+    end
+
+    # Out-parameters start at zero, so a slot the library never wrote reads
+    # as "absent" rather than as whatever was in that memory.
+    def zeroed(size)
+      slot = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
+      slot[0, size] = "\x00" * size
+      slot
+    end
+  end
+end

data/lib/shojiku/env.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # The one place this gem reads the environment.
+  #
+  # A client is constructed with `env: true` (the default) or `env: false`,
+  # and that single flag governs EVERY `SHOJIKU_*` lookup — the template root,
+  # the font and locale directories, and the library path. One flag rather
+  # than one per variable is the reference decision the other six SDKs mirror:
+  # an application that wants a hermetic configuration wants all of it off,
+  # and a per-variable set of knobs is a shape nobody can keep consistent
+  # across seven languages.
+  # Disabled lookups behave exactly as unset variables do, so calling code
+  # has no second branch to get wrong.
+  class Env
+    def initialize(enabled:, source: ENV)
+      @enabled = enabled
+      @source = source
+    end
+
+    # The variable's value, or nil when it is unset, blank, or lookups are off.
+    def [](name)
+      return nil unless @enabled
+
+      value = @source[name]
+      value if value && !value.empty?
+    end
+
+    # A `PATH_SEPARATOR`-separated variable as a list of directories, which is
+    # how every other tool in this family spells "several paths in one
+    # variable".
+    def paths(name)
+      value = self[name]
+      return [] unless value
+
+      value.split(File::PATH_SEPARATOR).reject(&:empty?)
+    end
+  end
+end

data/lib/shojiku/errors.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # The base of everything this gem raises.
+  #
+  # Raising is deliberately rare here. A template that will not render, a key
+  # that will not sign, a signature that does not verify are OUTCOMES — they
+  # come back as {Result} objects you query, never as exceptions you rescue.
+  # What is left for exceptions is what every Ruby library reserves them for:
+  # programmer misuse, and an environment that cannot host the engine at all.
+  class Error < StandardError; end
+
+  # The caller passed something this API cannot accept — a template name that
+  # is not a String, a nil where a value is required, both forms of the same
+  # material at once, an argument past a hard cap the C library documents, or
+  # an entrance this client's {Lockdown} disables. Programmer misuse, so it
+  # raises.
+  #
+  # A BLANK template name is deliberately not in that list: an empty string
+  # can arrive straight from a form field, so it comes back as a refused
+  # request like every other bad name.
+  class UsageError < Error; end
+
+  # Unwrapping a {Result} that failed.
+  #
+  # `artifact!` / `report!` are the opt-in bridge to exception-style control
+  # flow. Calling one on a failed result is programmer misuse — the ruling is
+  # explicit and frozen for every Shojiku SDK, because an accessor that raises
+  # is the one place this API could drift back into exceptions by accident.
+  # The failure travels on the exception, so nothing is lost by taking the
+  # short road.
+  class UnwrapError < Error
+    attr_reader :failure
+
+    def initialize(failure)
+      @failure = failure
+      super(failure.to_s)
+    end
+  end
+
+  # The engine library could not be found or loaded.
+  #
+  # The message names the install channels, because the fix is always an
+  # installation step and a bare loader error names none of them. Nothing in
+  # this gem downloads the library: an SDK that fetches an executable is a
+  # supply-chain surface this product does not take on.
+  class LibraryNotFound < Error; end
+
+  # The library loaded but implements a different ABI revision than this gem
+  # was written against. Loading anyway would mean calling symbols whose
+  # meaning has changed.
+  class AbiMismatch < Error; end
+
+  # Key, certificate or trust-anchor bytes that could not be read.
+  #
+  # Raised internally and caught by {Client}, which turns it into a failed
+  # {Result}: an unreadable key is an outcome of the operation, not a bug in
+  # the calling program. It carries the machine-readable `kind` the failure
+  # trace reports.
+  class MaterialUnreadable < Error
+    attr_reader :kind
+
+    def initialize(kind, message)
+      @kind = kind
+      super(message)
+    end
+  end
+
+  # Echoing caller-supplied text back in a message or a log line.
+  #
+  # Template names and provider names reach exception reporters and log files,
+  # so they are stripped of control characters and bounded before they are
+  # quoted — the same discipline the engine applies to the values it echoes.
+  # One place for it, because every path that echoes owes the same thing.
+  module Echo
+    LIMIT = 80
+
+    def self.bounded(text)
+      text.to_s.delete("\x00-\x1f\x7f")[0, LIMIT]
+    end
+  end
+
+  # Reading the byte inputs signing and verification take.
+  #
+  # One place, because both paths owe the same thing: binary mode (PEM is
+  # bytes, and a transcode would corrupt a DER-bearing file), and an
+  # unreadable file surfacing as {MaterialUnreadable} rather than as a raw
+  # `Errno` nobody upstream is catching.
+  module Material
+    def self.read(path, kind)
+      File.binread(path)
+    rescue SystemCallError => e
+      raise MaterialUnreadable.new(kind, e.message)
+    end
+  end
+end

data/lib/shojiku/failure.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # Why a lifecycle operation did not produce what was asked for.
+  #
+  # A VALUE, not an exception. The shape takes effect-ts's `Cause` as its
+  # conceptual reference: which step failed, what class of thing went wrong,
+  # and — when one failure happened because of another — the chain underneath
+  # it, all inspectable rather than unwound. No effect framework is involved;
+  # only the idea that a failure is data.
+  class Failure
+    # The lifecycle step, as a symbol: `:generate`, `:sign` or `:verify`.
+    #
+    # Always one of those three — the SDK's own vocabulary, from
+    # `docs/agents/sdk.md`. The engine's error object carries a step of its
+    # own naming an INTERNAL stage (`render`, `validate`), and passing that
+    # through would make the trace's step mean different things depending on
+    # which layer refused. What the engine said specifically is in {#kind}.
+    attr_reader :step
+
+    # A stable machine-readable class. Engine-side kinds come straight off the
+    # wire; host-side ones are this gem's own (`template_name`, `io`, …).
+    attr_reader :kind
+
+    attr_reader :message, :diagnostics, :cause
+
+    def self.from_error_json(json, step:, diagnostics: [], cause: nil)
+      parsed = json.nil? || json.empty? ? {} : JSON.parse(json)
+      new(
+        step: step,
+        kind: parsed.fetch("kind", "unknown"),
+        message: parsed.fetch("message", ""),
+        diagnostics: diagnostics,
+        cause: cause
+      )
+    end
+
+    def initialize(step:, kind:, message:, diagnostics: [], cause: nil)
+      @step = step.to_sym
+      @kind = kind
+      @message = message
+      @diagnostics = diagnostics
+      @cause = cause
+    end
+
+    # This failure and everything under it, outermost first. What you log when
+    # you want the whole story rather than only its headline.
+    def causes
+      [self] + (@cause ? @cause.causes : [])
+    end
+
+    def to_s
+      "#{@step}/#{@kind}: #{@message}"
+    end
+  end
+end

data/lib/shojiku/library.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+module Shojiku
+  # Finding and opening the engine's shared library.
+  #
+  # Resolution order, and the deliberate asymmetry with the template root:
+  # `SHOJIKU_LIBRARY` beats explicit configuration, which beats the copy
+  # shipped inside the platform gem. That is the reverse of how the template
+  # root resolves, and on purpose — WHERE THE ENGINE LIVES is an
+  # operator/deployment decision that has to be able to win over application
+  # code, exactly as `SHOJIKU_BIN` does for the subprocess SDKs. WHICH
+  # TEMPLATES an application renders is the application's own decision, so
+  # there the explicit value wins.
+  #
+  # Nothing here downloads anything. A library that is not present is a named
+  # error listing the install channels.
+  class Library
+    # The ABI revision this gem is written against. It moves only when a
+    # symbol's meaning changes; new operations are appended without it, so a
+    # newer engine keeps working with this gem.
+    ABI_VERSION = 1
+
+    # The names a platform gem's binary can have, in the order they are
+    # tried. Windows is the reason there are six rather than three: cargo
+    # emits `shojiku_capi.dll` with no `lib` prefix, while the Unix targets
+    # get one. Looking only for the prefixed form would make the gem
+    # unloadable on the platform the .NET market runs on.
+    NAMES = %w[.so .dylib .dll].flat_map do |suffix|
+      ["libshojiku_capi#{suffix}", "shojiku_capi#{suffix}"]
+    end.freeze
+
+    # Where a platform gem puts the binary it ships.
+    PACKAGED_DIR = File.expand_path("native", __dir__)
+
+    attr_reader :path
+
+    # Opens the library, or raises {LibraryNotFound} naming how to install it.
+    def initialize(path: nil, env: Env.new(enabled: true), log: Log.new)
+      @log = log
+      @path, @source = discover(path, env)
+      raise LibraryNotFound, install_hint("no engine library was found") unless @path
+
+      @handle = open_handle(@path)
+      @log.event(:library_loaded, path: @path, source: @source)
+      check_abi
+    end
+
+    # A declared foreign function. Types are always explicit: Fiddle's
+    # defaults would return a C `int` and truncate every pointer this surface
+    # hands back.
+    def function(name, args, returns)
+      Fiddle::Function.new(@handle[name.to_s], args, returns)
+    rescue Fiddle::DLError => e
+      raise LibraryNotFound, "#{@path} exports no `#{name}` (#{e.message})"
+    end
+
+    private
+
+    # The resolution order, and which position won — the second half is worth
+    # reporting, because "which library did this process actually load, and
+    # why that one" is the question a deployment asks at 3am.
+    def discover(path, env)
+      return [env["SHOJIKU_LIBRARY"], :environment] if env["SHOJIKU_LIBRARY"]
+      return [path, :configuration] if path
+
+      [packaged, :packaged]
+    end
+
+    def packaged
+      NAMES.map { |name| File.join(PACKAGED_DIR, name) }
+           .find { |candidate| File.file?(candidate) }
+    end
+
+    def open_handle(path)
+      Fiddle::Handle.new(path)
+    rescue Fiddle::DLError => e
+      raise LibraryNotFound, install_hint("#{path} could not be loaded (#{e.message})")
+    end
+
+    # Asked once, before anything else is called — the header's own advice,
+    # and the only way a binding learns that a symbol it is about to call
+    # means something different now.
+    def check_abi
+      found = function(:shojiku_abi_version, [], Fiddle::TYPE_INT).call
+      @log.event(:abi_checked, found: found, expected: ABI_VERSION)
+      return if found == ABI_VERSION
+
+      raise AbiMismatch,
+            "#{@path} implements ABI revision #{found}; this gem speaks #{ABI_VERSION}"
+    end
+
+    def install_hint(reason)
+      <<~MESSAGE.strip
+        #{reason}.
+
+        This gem never downloads the engine. Install it one of these ways:
+          * install the platform gem for your system, which ships the binary
+          * point SHOJIKU_LIBRARY at a libshojiku_capi library you built
+          * pass Shojiku::Client.new(library: "/path/to/libshojiku_capi.so")
+      MESSAGE
+    end
+  end
+end

data/lib/shojiku/local_pem.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Shojiku
+  # A signing provider backed by a PEM key and certificate.
+  #
+  # The only provider this release has. KMS and HSM providers are a recorded
+  # deferral, which is why this is a named class rather than a pair of
+  # arguments on `sign` — a second provider then adds a class, not a signature
+  # change in seven languages.
+  #
+  # The material comes either from paths (`key:` / `cert:`) or from bytes
+  # already in memory (`key_pem:` / `cert_pem:`), so a key fetched from a
+  # secret manager never has to be written to disk first. Which one you passed
+  # is explicit rather than sniffed: guessing whether a string is a path or a
+  # PEM body is exactly the kind of cleverness that reads the wrong file.
+  #
+  # Nothing here logs key material, and the engine builds its refusals from
+  # fixed strings, so a rejection cannot echo it back either.
+  class LocalPem
+    FORMS = "`%<what>s:` (a path) or `%<what>s_pem:` (bytes)"
+
+    attr_reader :passphrase
+
+    def initialize(key: nil, cert: nil, key_pem: nil, cert_pem: nil, passphrase: nil)
+      @key_path = key
+      @cert_path = cert
+      @key_pem = key_pem
+      @cert_pem = cert_pem
+      @passphrase = passphrase
+      one_source!(key, key_pem, "key")
+      one_source!(cert, cert_pem, "cert")
+    end
+
+    # Redacted, deliberately.
+    #
+    # The default `#inspect` prints every instance variable, which here is the
+    # private key and the passphrase — into a console, a `binding.irb`, an
+    # exception reporter's local-variable dump, or any log line that
+    # interpolates the provider. None of that is worth showing, so nothing is
+    # shown but the class and which FORM each half came from. Registering the
+    # provider once (see {Lockdown}) shrinks this surface further: material
+    # loads into one object instead of being rebuilt per request.
+    def inspect
+      "#<#{self.class.name} key=#{form(@key_path)} cert=#{form(@cert_path)} " \
+        "passphrase=#{@passphrase ? "[redacted]" : "none"}>"
+    end
+
+    def key
+      @key ||= @key_pem || Material.read(@key_path, "key_unreadable")
+    end
+
+    def certificate
+      @certificate ||= @cert_pem || Material.read(@cert_path, "certificate_unreadable")
+    end
+
+    private
+
+    # The path, or a note that the bytes came from memory. A configured file
+    # path is not secret and is the one thing worth seeing when a provider
+    # loaded the wrong material; the bytes themselves are never printed.
+    def form(path)
+      path ? path.to_s : "[pem bytes]"
+    end
+
+    # Explicit, never sniffed — in BOTH directions. Guessing whether a string
+    # is a path or a PEM body is how the wrong file gets read; accepting both
+    # forms and silently preferring one ignores the argument the caller meant,
+    # which is the same mistake one layer quieter.
+    def one_source!(path, pem, what)
+      forms = format(FORMS, what: what)
+      raise UsageError, "LocalPem takes either #{forms}, not both" if path && pem
+      return if path || pem
+
+      raise UsageError, "LocalPem needs either #{forms}"
+    end
+  end
+end