klenod-runtime 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2479157e269db0089e1ead92345eaf605cbd8e4138977af0950cc8003d42dac
+  data.tar.gz: 9b451904ee8f93cc7246098e7ec34991b8b1523239851a5be68f9650b99b7926
+SHA512:
+  metadata.gz: 8c40bb3320f1f32a106484d44ffcd51379864f1fa2b0046dc75994c8573e8e754d8b253a9e9e5b3a044c109fe7f3563ad2e9965803e8e446b16bd79eb850c3cf
+  data.tar.gz: de76f09e4915a6939becd5a10a51a567e32eedfbe196bf1d9ea039ec6586fd1c88a57555a523c3241156d702045ff70b421cde4081020e8f790a5ac09cdf6a91

data/README.md

@@ -0,0 +1,30 @@
+# klenod-runtime
+
+`klenod-runtime` loads and evaluates
+[Klenod](https://github.com/aalin/klenod) bundles in production.
+
+It contains only the runtime pieces needed after a bundle has already been built:
+
+- `Klenod::Runtime::Bundle`
+- `Klenod::Runtime::Mod`
+- lazy import support
+- source maps and backtrace rewriting
+
+This gem should stay free of build plugins and heavyweight build-time dependencies such as RMagick, Syntax Tree, Haml, CSS processing, or file watching.
+
+Use this gem in applications that load an existing bundle:
+
+```ruby
+require "klenod/runtime"
+
+bundle = Klenod::Runtime.load_bundle("dist/klenod.bundle")
+exports = bundle.exports("pages/server")
+```
+
+Production servers can explicitly preload bundled modules:
+
+```ruby
+bundle.preload_entrypoints
+```
+
+Build bundles with [klenod-build](https://github.com/aalin/klenod/tree/main/gems/klenod-build).

data/lib/klenod/runtime/backtrace_rewriter.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+#
+# Copyright Andrés Alin <andreas.alin@gmail.com>
+# License: AGPL-3.0
+
+module Klenod
+  module Runtime
+    class BacktraceRewriter
+      class BacktraceString < String
+        attr_reader :parsed_backtrace_entry
+
+        def initialize(entry)
+          super(entry.to_s)
+          @parsed_backtrace_entry = entry
+        end
+      end
+
+      ParsedBacktraceEntry =
+        Data.define(:file, :line, :description) do
+          def self.parse(line)
+            case line
+            in BacktraceString
+              line.parsed_backtrace_entry
+            in /\A(?<file>.*):(?<line>\d+):in '(?<description>.*)'\z/
+              new($~[:file], $~[:line].to_i, $~[:description])
+            else
+              nil
+            end
+          end
+
+          def to_s
+            "#{file}:#{line}:in '#{description}'"
+          end
+
+          def to_backtrace_string
+            BacktraceString.new(self)
+          end
+        end
+
+      def initialize(mods)
+        @source_maps = source_maps_for(mods)
+        @source_map_cache = Hash.new { |h, path| h[path] = @source_maps[path] }
+        @constant_display_names = constant_display_names_for(mods)
+      end
+
+      def format_exception(e, source_path: nil)
+        reset = "\e[0;48;5;52m"
+        rewrite_exception(e)
+        sources = format_sources(e.backtrace)
+
+        [
+          "\e[1;31;47m ERROR \e[3;31;47m #{e.class.name}: #{e.message} #{reset}",
+          "\e[1;34mBacktrace:#{reset}",
+          e
+            .backtrace
+            .map do |line|
+              if line in BacktraceString
+                format(
+                  "#{reset}\e[2mfrom #{reset}\e[1m%<file>s:%<line>d#{reset}\e[2m:in '#{reset}\e[1m%<description>s#{reset}\e[2m'#{reset}",
+                  line.parsed_backtrace_entry.to_h
+                )
+              else
+                "from #{line}"
+              end
+            end
+            .join("\n"),
+          formatted_sources(sources, reset)
+        ].compact.join("\n") + "\e[0m"
+      end
+
+      def rewrite_exception(e)
+        rewrite_exception_message(e)
+        e.set_backtrace(rewrite_backtrace(e.backtrace))
+      end
+
+      def rewrite_backtrace(backtrace)
+        backtrace.map do |line|
+          if (entry = ParsedBacktraceEntry.parse(line))
+            rewrite_backtrace_entry(entry).to_backtrace_string
+          else
+            line
+          end
+        end
+      end
+
+      private
+
+      def formatted_sources(sources, reset)
+        return nil if sources.empty?
+
+        [
+          "\e[1;34mSources:#{reset}",
+          sources
+            .map do |file, formatted_source|
+              "\e[1m#{file}\e[0m\n#{formatted_source}"
+            end
+            .join("\n")
+        ].join("\n")
+      end
+
+      def source_maps_for(mods)
+        mods.each_with_object({}) do |(key, mod), index|
+          next unless mod.respond_to?(:source_map)
+
+          source_map = mod.source_map
+          next unless source_map
+
+          index[key.to_s] = source_map
+          index[mod.path.to_s] = source_map if mod.respond_to?(:path)
+          index[mod.eval_path.to_s] = source_map if mod.respond_to?(:eval_path)
+        end
+      end
+
+      def rewrite_backtrace_entry(entry)
+        if (original_line_no = find_original_line_no(entry.file, entry.line))
+          entry.with(line: original_line_no, description: rewrite_const_paths(entry.description))
+        else
+          entry.with(description: rewrite_const_paths(entry.description))
+        end
+      end
+
+      def constant_display_names_for(mods)
+        mods.each_with_object({}) do |(key, mod), index|
+          next unless mod.respond_to?(:constant_name)
+
+          display_path = mod.respond_to?(:path) ? mod.path : key
+          index["Klenod::Runtime::Generated::#{mod.constant_name}"] = "Mod[#{display_path.inspect}]"
+        end
+      end
+
+      def rewrite_const_paths(value)
+        @constant_display_names.reduce(value.to_s) do |message, (generated_name, display_name)|
+          message.gsub(generated_name, display_name)
+        end
+      end
+
+      def rewrite_exception_message(error)
+        message = rewrite_const_paths(error.message)
+        return if message == error.message
+
+        error.define_singleton_method(:message) { message }
+        error.define_singleton_method(:to_s) { message }
+      end
+
+      def find_original_line_no(file, line_no)
+        @source_map_cache[file]&.find_original_line_no(line_no)
+      end
+
+      def format_sources(backtrace)
+        backtrace
+          .select { |line| line.is_a?(BacktraceString) }
+          .map(&:parsed_backtrace_entry)
+          .group_by(&:file)
+          .map do |file, entries|
+            if (source_map = @source_map_cache[file])
+              [file, format_source(source_map.input, entries.map(&:line))]
+            end
+          end
+          .compact
+          .to_h
+      end
+
+      def format_source(source, interesting_lines)
+        ranges =
+          merge_overlapping_ranges(interesting_lines.map { (it - 2)..(it + 2) })
+        lines = source.each_line.to_a
+
+        ranges
+          .map do |range|
+            range
+              .map do |i|
+                next if i <= 0
+                line = lines[i - 1]
+                next unless line
+
+                str = format("%3d: %s", i, line.chomp)
+                interesting_lines.include?(i) ? "\e[1;31m#{str}\e[0m" : str
+              end
+              .compact
+              .join("\n")
+          end
+          .join("\n\e[37;44m ... \e[0m\n")
+      end
+
+      def merge_overlapping_ranges(ranges)
+        ranges.each_with_object([]) do |range, merged|
+          if (idx = merged.find_index { |r| r.overlap?(range) })
+            overlapping = merged[idx]
+            merged[idx] = [overlapping.begin, range.begin].min..[
+              overlapping.end,
+              range.end
+            ].max
+          else
+            merged << range
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klenod/runtime/bundle.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+module Klenod
+  module Runtime
+    ModuleSpec =
+      Data.define(:id, :source_path, :source, :imports, :source_map, :version, :constant_name)
+
+    ImportSpec = Data.define(:target_id, :value, :eager)
+    DefaultImport = Data.define(:name)
+
+    AssetSpec =
+      Data.define(:logical_name, :content_hash, :output_path, :content_type, :metadata)
+    AssetReference = Data.define(:index, :asset)
+
+    class Bundle
+      attr_reader :entrypoints, :modules, :assets, :source_root
+
+      def self.load(source, source_root: nil)
+        BundleFormat.load(source, source_root: source_root)
+      end
+
+      def self.load_file(path, source_root: nil)
+        load(path, source_root: source_root)
+      end
+
+      def initialize(entrypoints, modules, assets, source_root: nil)
+        @entrypoints = entrypoints
+        @modules = modules
+        @assets = assets
+        @source_root = source_root
+        @mods = {}
+      end
+
+      def load(entrypoint = nil)
+        id =
+          if entrypoint
+            entrypoint
+          elsif entrypoints.respond_to?(:values)
+            entrypoints.values.first
+          else
+            entrypoints.first
+          end
+
+        id = id.to_s
+        id = entrypoints.fetch(id, id) if entrypoints.respond_to?(:fetch)
+
+        instantiate(id)
+      end
+
+      def load_entrypoints
+        entrypoint_ids = entrypoints.respond_to?(:values) ? entrypoints.values : entrypoints
+        entrypoint_ids.map { |entrypoint| load(entrypoint) }
+      end
+
+      def preload(module_ref = nil)
+        module_ids =
+          if module_ref
+            reachable_module_ids(module_ref)
+          else
+            @modules.keys
+          end
+
+        module_ids.map { |module_id| instantiate(module_id) }
+      end
+
+      def preload_entrypoints
+        entrypoint_ids = entrypoints.respond_to?(:values) ? entrypoints.values : entrypoints
+        seen = Set.new
+        module_ids =
+          entrypoint_ids
+            .flat_map { |entrypoint| reachable_module_ids(entrypoint) }
+            .select { |module_id| seen.add?(module_id) }
+        module_ids.map { |module_id| instantiate(module_id) }
+      end
+
+      def exports(entrypoint = nil)
+        load(entrypoint).const_get(:Exports)
+      end
+
+      def mod(id)
+        @mods.fetch(id.to_s)
+      end
+
+      def asset(output_path)
+        @assets.fetch(output_path)
+      end
+
+      def assets_for(logical_name)
+        @assets.values.select { |asset| asset.logical_name == logical_name.to_s }
+      end
+
+      def assets_for_module(module_ref, type: nil, content_type: nil, recursive: true)
+        asset_references_for_module(module_ref, type: type, content_type: content_type, recursive: recursive)
+          .map(&:asset)
+      end
+
+      def asset_references_for_module(module_ref, type: nil, content_type: nil, recursive: true)
+        seen_assets = {}
+        module_ids_for_assets(module_ref, recursive: recursive)
+          .each_with_index
+          .flat_map do |module_id, index|
+            assets_for_runtime_module(module_id).filter_map do |asset|
+              next unless asset_matches?(asset, type: type, content_type: content_type)
+              next if seen_assets.key?(asset.output_path)
+
+              seen_assets[asset.output_path] = true
+              AssetReference.new(index:, asset:)
+            end
+          end
+      end
+
+      def each_asset(&block)
+        return enum_for(:each_asset) unless block
+
+        @assets.each_value(&block)
+      end
+
+      def source_root=(source_root)
+        @source_root = source_root&.to_s
+        @mods = {}
+      end
+
+      def marshal_dump
+        [@entrypoints, @modules, @assets, @source_root]
+      end
+
+      def marshal_load(data)
+        @entrypoints, @modules, @assets, @source_root = data
+        @mods = {}
+      end
+
+      def module_id_for(module_ref)
+        id = module_ref.respond_to?(:path) ? module_ref.path : module_ref.to_s
+        id = entrypoints.fetch(id, id) if entrypoints.respond_to?(:fetch)
+        return id if @modules.key?(id)
+        canonical_module_id = module_id_for_canonical_ref(id)
+        return canonical_module_id if canonical_module_id
+
+        if (relative_id = module_id_for_absolute_ref(id))
+          return relative_id
+        end
+
+        raise KeyError, "No module in bundle for #{module_ref.inspect}"
+      end
+
+      private
+
+      def assets_for_runtime_module(module_id)
+        module_spec = @modules.fetch(module_id)
+        logical_names = [module_spec.id, module_spec.source_path].uniq
+        @assets.values.select { |asset| logical_names.include?(asset.logical_name) }
+      end
+
+      SCHEME_PATTERN = /\A[A-Za-z][A-Za-z0-9+.-]*:/
+
+      def module_id_for_canonical_ref(id)
+        canonical =
+          if id.match?(SCHEME_PATTERN)
+            canonical_scheme_ref(id)
+          elsif !id.start_with?("/")
+            "app:/#{id.delete_prefix("/")}"
+          end
+
+        canonical if canonical && @modules.key?(canonical)
+      end
+
+      def canonical_scheme_ref(id)
+        scheme, rest = id.split(":", 2)
+        return id if rest.start_with?("/", "//")
+
+        "#{scheme}:/#{rest}"
+      end
+
+      def module_id_for_absolute_ref(id)
+        return nil unless source_root
+
+        root = File.expand_path(source_root)
+        path = File.expand_path(id)
+        return nil unless path.start_with?("#{root}/")
+
+        relative = path.delete_prefix("#{root}/")
+        relative if @modules.key?(relative)
+      end
+
+      def reachable_module_ids(module_ref)
+        root_id = module_id_for(module_ref)
+        seen = Set.new
+        ordered = []
+        queue = [root_id]
+        index = 0
+
+        while index < queue.length
+          module_id = queue[index]
+          index += 1
+          next unless seen.add?(module_id)
+          next unless @modules.key?(module_id)
+
+          ordered << module_id
+          queue.concat(
+            @modules
+              .fetch(module_id)
+              .imports
+              .values
+              .map { |import_spec| import_spec.is_a?(ImportSpec) ? import_spec.target_id : import_spec }
+          )
+        end
+
+        ordered
+      end
+
+      def module_ids_for_assets(module_ref, recursive:)
+        return Array(module_ref).map { |ref| module_id_for(ref) }.uniq unless recursive
+
+        seen = []
+        Array(module_ref).flat_map do |ref|
+          ordered_module_ids_for_assets(module_id_for(ref), seen)
+        end
+      end
+
+      def ordered_module_ids_for_assets(module_id, seen)
+        return [] if seen.include?(module_id)
+        return [] unless @modules.key?(module_id)
+
+        seen << module_id
+        dependency_ids =
+          @modules
+            .fetch(module_id)
+            .imports
+            .values
+            .map { |import_spec| import_spec.is_a?(ImportSpec) ? import_spec.target_id : import_spec }
+
+        if File.extname(module_id) == ".css"
+          dependency_ids.flat_map { |dependency_id| ordered_module_ids_for_assets(dependency_id, seen) } + [module_id]
+        else
+          [module_id] + dependency_ids.flat_map { |dependency_id| ordered_module_ids_for_assets(dependency_id, seen) }
+        end
+      end
+
+      def asset_matches?(asset, type:, content_type:)
+        return false if type && asset.metadata[:type] != type
+        return false if content_type && asset.content_type != content_type
+
+        true
+      end
+
+      def instantiate(id)
+        id = id.to_s
+        return @mods.fetch(id) if @mods.key?(id)
+
+        spec = @modules.fetch(id)
+        imports =
+          spec.imports.to_h do |dependency_id, target_id|
+            import_spec =
+              if target_id.is_a?(ImportSpec)
+                target_id
+              else
+                ImportSpec.new(target_id, nil, true)
+              end
+
+            value =
+              if import_spec.eager
+                resolve_import_value(import_spec)
+              else
+                LazyImport.new { resolve_import_value(import_spec) }
+              end
+            [dependency_id, value]
+          end
+
+        @mods[id] =
+          Mod.new(
+            spec.id,
+            spec.source,
+            imports: imports,
+            source_map: spec.source_map,
+            version: spec.version,
+            constant_name: spec.constant_name,
+            eval_path: eval_path_for(spec)
+          )
+      end
+
+      def eval_path_for(spec)
+        return spec.source_path unless source_root
+
+        File.join(source_root, spec.source_path)
+      end
+
+      def resolve_import_value(import_spec)
+        exports = instantiate(import_spec.target_id).const_get(:Exports)
+
+        case import_spec.value
+        when DefaultImport
+          exports.const_get(import_spec.value.name)
+        else
+          import_spec.value || exports
+        end
+      end
+    end
+  end
+end
+
+require_relative "bundle_format"

data/lib/klenod/runtime/bundle_format.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "version"
+require_relative "source_map"
+
+module Klenod
+  module Runtime
+    class BundleFormatError < StandardError
+    end
+
+    module BundleFormat
+      MAGIC = "MODPACK_BUNDLE_V1\n"
+      FORMAT_VERSION = 1
+
+      module_function
+
+      def dump(bundle)
+        MAGIC + JSON.generate(payload_for(bundle))
+      end
+
+      def load(source, source_root: nil)
+        load_bytes(read_source(source), source_root: source_root)
+      end
+
+      def load_bytes(bytes, source_root: nil)
+        raise BundleFormatError, "Invalid Klenod bundle header" unless bytes.start_with?(MAGIC)
+
+        body = bytes.byteslice(MAGIC.bytesize, bytes.bytesize - MAGIC.bytesize)
+        payload = JSON.parse(body)
+        bundle_from_payload(payload, source_root: source_root)
+      rescue JSON::ParserError => error
+        raise BundleFormatError, "Invalid Klenod bundle JSON: #{error.message}"
+      end
+
+      def payload_for(bundle)
+        {
+          "format_version" => FORMAT_VERSION,
+          "runtime_version" => Runtime::VERSION,
+          "source_root" => encode_value(bundle.source_root),
+          "entrypoints" => encode_value(bundle.entrypoints),
+          "modules" => encode_modules(bundle.modules),
+          "assets" => encode_assets(bundle.assets)
+        }
+      end
+
+      def bundle_from_payload(payload, source_root: nil)
+        validate_payload!(payload)
+
+        bundle =
+          Bundle.new(
+            decode_value(payload.fetch("entrypoints")),
+            decode_modules(payload.fetch("modules")),
+            decode_assets(payload.fetch("assets")),
+            source_root: decode_value(payload["source_root"])
+          )
+        bundle.source_root = source_root if source_root
+        bundle
+      end
+
+      def read_source(source)
+        source.respond_to?(:read) ? source.read : File.binread(source)
+      end
+
+      def validate_payload!(payload)
+        raise BundleFormatError, "Malformed Klenod bundle payload" unless payload.is_a?(Hash)
+
+        version = payload["format_version"]
+        unless version == FORMAT_VERSION
+          raise BundleFormatError, "Unsupported Klenod bundle format version: #{version.inspect}"
+        end
+
+        %w[runtime_version source_root entrypoints modules assets].each do |key|
+          raise BundleFormatError, "Malformed Klenod bundle payload: missing #{key}" unless payload.key?(key)
+        end
+      end
+
+      def encode_modules(modules)
+        modules.to_h do |id, spec|
+          [
+            id.to_s,
+            {
+              "id" => spec.id,
+              "source_path" => spec.source_path,
+              "source" => spec.source,
+              "imports" => encode_imports(spec.imports),
+              "source_map" => encode_source_map(spec.source_map),
+              "version" => spec.version,
+              "constant_name" => spec.constant_name
+            }
+          ]
+        end
+      end
+
+      def decode_modules(payload)
+        expect_hash!(payload, "modules").to_h do |id, spec_payload|
+          spec_payload = expect_hash!(spec_payload, "module #{id}")
+          [
+            id,
+            ModuleSpec.new(
+              spec_payload.fetch("id"),
+              spec_payload.fetch("source_path"),
+              spec_payload.fetch("source"),
+              decode_imports(spec_payload.fetch("imports")),
+              decode_source_map(spec_payload["source_map"], spec_payload.fetch("source")),
+              spec_payload.fetch("version"),
+              spec_payload.fetch("constant_name")
+            )
+          ]
+        end
+      end
+
+      def encode_imports(imports)
+        imports.to_h { |name, import| [name.to_s, encode_import(import)] }
+      end
+
+      def decode_imports(payload)
+        expect_hash!(payload, "imports").to_h { |name, import| [name, decode_import(import)] }
+      end
+
+      def encode_import(import)
+        case import
+        when ImportSpec
+          {
+            "type" => "import_spec",
+            "target_id" => import.target_id,
+            "value" => encode_value(import.value),
+            "eager" => import.eager
+          }
+        else
+          {
+            "type" => "module_id",
+            "target_id" => import.to_s
+          }
+        end
+      end
+
+      def decode_import(payload)
+        payload = expect_hash!(payload, "import")
+        case payload.fetch("type")
+        when "import_spec"
+          ImportSpec.new(payload.fetch("target_id"), decode_value(payload["value"]), payload.fetch("eager"))
+        when "module_id"
+          payload.fetch("target_id")
+        else
+          raise BundleFormatError, "Unknown import type: #{payload["type"].inspect}"
+        end
+      end
+
+      def encode_assets(assets)
+        assets.to_h do |output_path, asset|
+          [
+            output_path.to_s,
+            {
+              "logical_name" => asset.logical_name,
+              "content_hash" => asset.content_hash,
+              "output_path" => asset.output_path,
+              "content_type" => asset.content_type,
+              "metadata" => encode_value(asset.metadata)
+            }
+          ]
+        end
+      end
+
+      def decode_assets(payload)
+        expect_hash!(payload, "assets").to_h do |output_path, asset_payload|
+          asset_payload = expect_hash!(asset_payload, "asset #{output_path}")
+          [
+            output_path,
+            AssetSpec.new(
+              asset_payload.fetch("logical_name"),
+              asset_payload.fetch("content_hash"),
+              asset_payload.fetch("output_path"),
+              asset_payload.fetch("content_type"),
+              decode_value(asset_payload.fetch("metadata"))
+            )
+          ]
+        end
+      end
+
+      def encode_source_map(source_map)
+        return nil unless source_map
+
+        {
+          "input" => source_map.input,
+          "marks_by_output_line" =>
+            source_map.marks_by_output_line.to_h do |line, mark|
+              [line.to_s, mark.line]
+            end
+        }
+      end
+
+      def decode_source_map(payload, output)
+        return nil unless payload
+
+        payload = expect_hash!(payload, "source map")
+        marks =
+          expect_hash!(payload.fetch("marks_by_output_line"), "source map marks").to_h do |line, source_line|
+            [line.to_i, SourceMap::Mark.new(source_line)]
+          end
+        SourceMap::SourceMap.new(payload.fetch("input"), output, marks.freeze)
+      end
+
+      def encode_value(value)
+        case value
+        when nil, true, false, String, Integer, Float
+          value
+        when Symbol
+          {"__klenod_type" => "symbol", "value" => value.to_s}
+        when Array
+          value.map { |item| encode_value(item) }
+        when Hash
+          {
+            "__klenod_type" => "hash",
+            "entries" =>
+              value.map do |key, hash_value|
+                [encode_value(key), encode_value(hash_value)]
+              end
+          }
+        when DefaultImport
+          {"__klenod_type" => "default_import", "name" => value.name.to_s}
+        else
+          raise BundleFormatError, "Cannot encode bundle value: #{value.class}"
+        end
+      end
+
+      def decode_value(value)
+        case value
+        when nil, true, false, String, Integer, Float
+          value
+        when Array
+          value.map { |item| decode_value(item) }
+        when Hash
+          case value["__klenod_type"]
+          when "symbol"
+            value.fetch("value").to_sym
+          when "hash"
+            value.fetch("entries").to_h do |key, hash_value|
+              [decode_value(key), decode_value(hash_value)]
+            end
+          when "default_import"
+            DefaultImport.new(value.fetch("name").to_sym)
+          else
+            value.to_h { |key, hash_value| [key, decode_value(hash_value)] }
+          end
+        else
+          raise BundleFormatError, "Cannot decode bundle value: #{value.class}"
+        end
+      end
+
+      def expect_hash!(value, label)
+        return value if value.is_a?(Hash)
+
+        raise BundleFormatError, "Malformed Klenod bundle payload: #{label} must be an object"
+      end
+    end
+  end
+end

data/lib/klenod/runtime/mod.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Klenod
+  module Runtime
+    module Generated
+    end
+
+    class LazyImport
+      def initialize(&loader)
+        @loader = loader
+        @loaded = false
+        @value = nil
+      end
+
+      def call
+        return @value if @loaded
+
+        @value = @loader.call
+        @loaded = true
+        @value
+      end
+
+      alias_method :value, :call
+
+      def loaded?
+        @loaded
+      end
+
+      def reset!
+        @loaded = false
+        @value = nil
+        self
+      end
+    end
+
+    class Mod < Module
+      class Exports < Module
+        def initialize(mod, imports)
+          @mod = mod
+          @imports = imports
+        end
+
+        def inspect
+          "#{@mod.inspect}::Exports"
+        end
+
+        def __klenod_import__(dependency_id)
+          @imports.fetch(dependency_id)
+        end
+
+        def __klenod_lazy_import__(dependency_id)
+          @imports.fetch(dependency_id)
+        end
+      end
+
+      attr_reader :path, :source, :source_map, :version, :constant_name, :eval_path
+
+      def self.constant_name_for(path)
+        "Mod_#{Digest::SHA256.hexdigest(path)[0, 24]}"
+      end
+
+      def inspect
+        "Mod(#{path.inspect})"
+      end
+
+      def initialize(path, source, imports: {}, source_map: nil, version: 0, constant_name: nil, eval_path: nil)
+        @path = path
+        @source = source
+        @imports = imports
+        @source_map = source_map
+        @version = version
+        @constant_name = constant_name || self.class.constant_name_for(path)
+        @eval_path = eval_path || path
+        register_constant
+        create_exports
+      end
+
+      def marshal_dump
+        [@path, @source, @source_map, @version, @constant_name, @eval_path]
+      end
+
+      def marshal_load(data)
+        @path, @source, @source_map, @version, @constant_name, @eval_path = data
+        @eval_path ||= @path
+        @imports = {}
+        register_constant
+        create_exports
+      end
+
+      def to_s
+        "#<#{self.class.name} path=#{@path.inspect}>"
+      end
+
+      private
+
+      def register_constant
+        Generated.__send__(:remove_const, @constant_name) if Generated.const_defined?(@constant_name, false)
+        Generated.const_set(@constant_name, self)
+      end
+
+      def create_exports
+        remove_const(:Exports) if const_defined?(:Exports, false)
+
+        exports = Exports.new(self, @imports)
+        exports.module_eval(@source, @eval_path, 1)
+        const_set(:Exports, exports)
+      end
+    end
+  end
+end

data/lib/klenod/runtime/source_map.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Klenod
+  module Runtime
+    module SourceMap
+      MARK_PREFIX = "SourceMapMark"
+
+      Mark = Data.define(:line) do
+        def self.parse(value)
+          return value if value.is_a?(self)
+          return nil unless value
+
+          if value =~ /\A#{MARK_PREFIX}:(?<line>\d+):?\z/
+            new($~[:line].to_i)
+          end
+        end
+
+        def to_s
+          "#{MARK_PREFIX}:#{line}"
+        end
+      end
+
+      SourceMap = Data.define(:input, :output, :marks_by_output_line) do
+        def self.parse(input, output)
+          marks = {}
+          return new(input, output, marks.freeze) unless output.include?(MARK_PREFIX)
+
+          output.each_line.with_index(1) do |line, line_no|
+            if (mark = parse_line_mark(line))
+              marks[line_no] = mark
+            end
+          end
+
+          new(input, output, marks.freeze)
+        end
+
+        def self.parse_line_mark(line)
+          start = line.index(MARK_PREFIX)
+          return nil unless start
+
+          index = start + MARK_PREFIX.length
+          return nil unless line.getbyte(index) == 58 # :
+
+          index += 1
+          line_start = index
+          index += 1 while (byte = line.getbyte(index)) && byte >= 48 && byte <= 57
+          return nil if index == line_start
+
+          Mark.new(line.byteslice(line_start, index - line_start).to_i)
+        end
+
+        def find_original_line_no(output_line_no)
+          # Marks apply until the next mark, so generated code only needs a mark
+          # before the expression it came from.
+          marks_by_output_line
+            .select { |line_no, _mark| line_no <= output_line_no }
+            .max_by { |line_no, _mark| line_no }
+            &.last
+            &.line
+        end
+      end
+    end
+  end
+end

data/lib/klenod/runtime/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Klenod
+  module Runtime
+    VERSION = "0.0.1"
+  end
+end

data/lib/klenod/runtime.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "runtime/version"
+require_relative "runtime/source_map"
+require_relative "runtime/backtrace_rewriter"
+require_relative "runtime/mod"
+require_relative "runtime/bundle"
+require_relative "runtime/bundle_format"
+
+module Klenod
+  module Runtime
+    EXECUTABLE_BUNDLE_MARKER = "\n__END__\n".b.freeze
+
+    def self.load_bundle(source, source_root: nil)
+      Bundle.load(source, source_root: source_root)
+    end
+
+    def self.load_bundle_in_box(source, source_root: nil, box: nil)
+      unless defined?(Ruby::Box) && Ruby::Box.enabled?
+        raise "Ruby::Box is disabled. Set RUBY_BOX=1 environment variable to use Ruby::Box."
+      end
+
+      bytes = source.respond_to?(:read) ? source.read : File.binread(source)
+      box = prepare_box(box)
+      box::Klenod::Runtime::BundleFormat.load_bytes(bytes, source_root: source_root)
+    end
+
+    def self.prepare_box(box = nil)
+      unless defined?(Ruby::Box) && Ruby::Box.enabled?
+        raise "Ruby::Box is disabled. Set RUBY_BOX=1 environment variable to use Ruby::Box."
+      end
+
+      box ||= Ruby::Box.new
+      box.require(File.expand_path(__FILE__)) unless runtime_loaded_in_box?(box)
+      box
+    end
+
+    def self.runtime_loaded_in_box?(box)
+      box.const_defined?(:Klenod, false) &&
+        box::Klenod.const_defined?(:Runtime, false)
+    end
+
+    def self.load_executable_bundle(path, source_root: nil)
+      bytes = File.binread(path)
+      marker_index = bytes.index(EXECUTABLE_BUNDLE_MARKER)
+      raise ArgumentError, "Missing __END__ marker in executable bundle: #{path}" unless marker_index
+
+      payload = bytes.byteslice(marker_index + EXECUTABLE_BUNDLE_MARKER.bytesize, bytes.bytesize)
+      BundleFormat.load_bytes(payload, source_root: source_root)
+    end
+  end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: klenod-runtime
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andrés Alin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Klenod runtime loads serialized Ruby module bundles without build plugins
+  or development dependencies.
+email:
+- andreas.alin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/klenod/runtime.rb
+- lib/klenod/runtime/backtrace_rewriter.rb
+- lib/klenod/runtime/bundle.rb
+- lib/klenod/runtime/bundle_format.rb
+- lib/klenod/runtime/mod.rb
+- lib/klenod/runtime/source_map.rb
+- lib/klenod/runtime/version.rb
+homepage: https://github.com/aalin/klenod
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aalin/klenod
+  source_code_uri: https://github.com/aalin/klenod/tree/main/gems/klenod-runtime
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.6
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Runtime loader for Klenod bundles.
+test_files: []