ibex 0.1.0 → 0.3.0

data/lib/ibex/generation_transaction.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require_relative "error"
+require_relative "generation_transaction_recovery"
+require_relative "generation_transaction_validation"
+
+module Ibex
+  # Publishes a rendered ArtifactSet with rollback and a manifest-last marker.
+  class GenerationTransaction
+    include GenerationTransactionRecovery
+    include GenerationTransactionValidation
+
+    class SourceChanged < Ibex::Error; end
+
+    class Error < Ibex::Error
+      attr_reader :rollback_failed #: bool
+      attr_reader :recovery_artifacts #: Array[String]
+
+      # @rbs (String message, ?rollback_failed: bool, ?recovery_artifacts: Array[String]) -> void
+      def initialize(message, rollback_failed: false, recovery_artifacts: [])
+        super(message)
+        @rollback_failed = rollback_failed
+        @recovery_artifacts = recovery_artifacts.freeze
+      end
+    end
+
+    # rubocop:disable Layout/LineLength
+    # @rbs (ArtifactSet artifacts, ?warning: ^(String) -> void, ?stability_check: ^() -> bool, ?source_records: Array[GenerationInput], ?lock_sleeper: ^(Float) -> void) -> void
+    def initialize(artifacts, warning: ->(_message) {}, stability_check: -> { true }, source_records: [],
+                   lock_sleeper: ->(seconds) { sleep(seconds) })
+      @artifacts = artifacts
+      @warning = warning
+      @stability_check = stability_check
+      @source_records = source_records
+      @lock_sleeper = lock_sleeper
+      @locks = [] #: Array[File]
+      @locked_paths = [] #: Array[String]
+      @records = [] #: Array[Hash[Symbol, Object?]]
+      @committed = false
+      @temporary_sequence = 0
+    end
+    # rubocop:enable Layout/LineLength
+
+    # @rbs () -> void
+    def commit
+      @committed = false
+      prepare_records
+      validate_source_boundaries!
+      acquire_locks
+      prepare_records
+      validate_source_boundaries!
+      validate_locked_targets!
+      ensure_sources_stable!("before staging outputs")
+      stage_records
+      ensure_sources_stable!("while staging outputs")
+      backup_records
+      sync_directories!
+      install_group(:non_marker)
+      sync_directories!
+      ensure_sources_stable!("before parser publication")
+      install_group(:parser)
+      sync_directories!
+      ensure_sources_stable!("after parser publication")
+      install_group(:manifest)
+      sync_directories!
+      ensure_sources_stable!("after manifest publication")
+      @committed = true
+      cleanup_success
+    rescue StandardError, SignalException => e
+      @committed ? report_post_commit_failure(e) : handle_failure(e)
+    ensure
+      release_locks
+    end
+
+    private
+
+    # @rbs () -> void
+    def prepare_records
+      @records = @artifacts.map do |artifact|
+        target = resolved_target(artifact.path)
+        {
+          artifact: artifact, target: target, directory: File.dirname(target),
+          stage: nil, backup: nil, backed_up: false, installed: false,
+          existed: File.exist?(target), mode: target_mode(artifact, target)
+        }
+      end
+      grouped = @records.group_by do |record|
+        portable_target_key(record.fetch(:target))
+      end
+      collision = grouped.find { |_key, records| records.length > 1 }
+      return unless collision
+
+      kinds = collision.fetch(1).map { |record| record.fetch(:artifact).kind }.join(", ")
+      targets = collision.fetch(1).map { |record| record.fetch(:target) }.join(", ")
+      raise Error, "(generation):1:1: artifact targets collide: #{targets} (#{kinds})"
+    end
+
+    # @rbs (Artifact artifact, String target) -> Integer
+    def target_mode(artifact, target)
+      return artifact.mode if artifact.mode
+      return File.stat(target).mode & 0o7777 if File.exist?(target)
+
+      mask = File.umask
+      File.umask(mask)
+      0o666 & ~mask
+    end
+
+    # @rbs () -> void
+    def acquire_locks
+      lock_paths = @records.map { |record| lock_path(record.fetch(:target)) }.uniq.sort
+      validate_lock_boundaries!(lock_paths)
+      @locked_paths = lock_paths
+      @locks = [] #: Array[File]
+      lock_paths.each do |path|
+        flags = File::RDWR | File::CREAT
+        flags |= File.const_get(:NOFOLLOW) if File.const_defined?(:NOFOLLOW)
+        lock = File.new(path, flags, 0o600)
+        @locks << lock
+        validate_lock_identity!(path, lock)
+        acquire_lock(lock, path)
+        validate_lock_identity!(path, lock)
+      end
+    end
+
+    # @rbs (File lock, String path) -> void
+    def acquire_lock(lock, path)
+      until lock.flock(File::LOCK_EX | File::LOCK_NB)
+        unless @stability_check.call
+          raise SourceChanged, "(generation):1:1: generation cancelled while waiting for lock: #{path}"
+        end
+
+        @lock_sleeper.call(0.05)
+      end
+    end
+
+    # @rbs (String target) -> String
+    def lock_path(target)
+      digest = Digest::SHA256.hexdigest(target).slice(0, 16)
+      File.join(File.dirname(target), ".ibex-generation-#{digest}.lock")
+    end
+
+    # @rbs () -> void
+    def stage_records
+      @records.each do |record|
+        temporary = create_temporary_file(record.fetch(:directory), ".stage")
+        begin
+          record[:stage] = temporary.path.dup
+          temporary.binmode
+          temporary.write(record.fetch(:artifact).content)
+          temporary.flush
+          temporary.chmod(record.fetch(:mode))
+          temporary.fsync
+        ensure
+          temporary.close
+        end
+      end
+    end
+
+    # @rbs () -> void
+    def backup_records
+      @records.each do |record|
+        target = record.fetch(:target)
+        next unless File.exist?(target)
+
+        validate_existing_target!(target)
+        backup = create_backup_link(target, record.fetch(:directory))
+        record[:backup] = backup
+        record[:backed_up] = true
+      end
+    end
+
+    # @rbs (String directory, String suffix) -> File
+    def create_temporary_file(directory, suffix)
+      with_temporary_path(directory, suffix) do |path|
+        flags = File::WRONLY | File::CREAT | File::EXCL
+        flags |= File.const_get(:NOFOLLOW) if File.const_defined?(:NOFOLLOW)
+        return File.new(path, flags, 0o600)
+      end
+      raise Error, "(generation):1:1: temporary file is unavailable in #{directory}"
+    end
+
+    # @rbs (String target, String directory) -> String
+    def create_backup_link(target, directory)
+      with_temporary_path(directory, ".backup") do |path|
+        File.link(target, path)
+        return path
+      end
+      raise Error, "(generation):1:1: backup path is unavailable in #{directory}"
+    end
+
+    # @rbs (String directory, String suffix) { (String) -> void } -> void
+    def with_temporary_path(directory, suffix)
+      100.times do
+        @temporary_sequence += 1
+        name = ".ibex-generation-#{Process.pid}-#{object_id.to_s(36)}-#{@temporary_sequence.to_s(36)}#{suffix}"
+        yield File.join(directory, name)
+      rescue Errno::EEXIST
+        next
+      end
+    end
+
+    # @rbs (Symbol group) -> void
+    def install_group(group)
+      selected = @records.select { |record| publication_group(record.fetch(:artifact)) == group }
+      selected.sort_by { |record| record.fetch(:target) }.each do |record|
+        File.rename(record.fetch(:stage), record.fetch(:target))
+        record[:stage] = nil
+        record[:installed] = true
+      end
+    end
+
+    # @rbs (Artifact artifact) -> Symbol
+    def publication_group(artifact)
+      return :manifest if artifact.kind == :manifest
+      return :parser if artifact.kind == :parser
+
+      :non_marker
+    end
+
+    # @rbs () -> void
+    def sync_directories!
+      @records.map { |record| record.fetch(:directory) }.uniq.sort.each do |directory|
+        File.open(directory, File::RDONLY, &:fsync)
+      end
+    end
+
+    # @rbs () -> void
+    def cleanup_success
+      failures = cleanup_artifacts(preserve_backups: false)
+      sync_failures = sync_directories_best_effort
+      messages = failures + sync_failures
+      warn_best_effort("generation cleanup incomplete: #{messages.join('; ')}") unless messages.empty?
+    end
+
+    # @rbs (Exception error) -> void
+    def report_post_commit_failure(error)
+      warn_best_effort("generation committed but cleanup failed: #{error.message}")
+    end
+
+    # @rbs (String message) -> void
+    def warn_best_effort(message)
+      @warning.call(message)
+    rescue StandardError
+      nil
+    end
+
+    # @rbs () -> void
+    def release_locks
+      @locks.reverse_each do |lock|
+        lock.flock(File::LOCK_UN)
+        lock.close
+      rescue StandardError
+        nil
+      end
+      @locks = [] #: Array[File]
+      @locked_paths = [] #: Array[String]
+    end
+  end
+end

data/lib/ibex/generation_transaction_recovery.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # Failure recovery and best-effort cleanup for GenerationTransaction.
+  module GenerationTransactionRecovery
+    private
+
+    # @rbs (Exception cause) -> bot
+    def handle_failure(cause)
+      rollback_failures = rollback
+      cleanup_failures = cleanup_artifacts(preserve_backups: !rollback_failures.empty?)
+      sync_failures = sync_directories_best_effort
+      raise cause if source_change_clean?(cause, rollback_failures, cleanup_failures, sync_failures)
+
+      recovery = recovery_artifacts
+      details = failure_details(cause, rollback_failures, cleanup_failures, sync_failures, recovery)
+      raise GenerationTransaction::Error.new(
+        "(generation):1:1: #{details.join(' | ')}",
+        rollback_failed: !rollback_failures.empty?, recovery_artifacts: recovery
+      ), cause: cause
+    end
+
+    # @rbs (Exception cause, Array[String] rollback, Array[String] cleanup, Array[String] sync) -> bool
+    def source_change_clean?(cause, rollback, cleanup, sync)
+      cause.is_a?(GenerationTransaction::SourceChanged) && rollback.empty? && cleanup.empty? && sync.empty?
+    end
+
+    # rubocop:disable Layout/LineLength
+    # @rbs (Exception cause, Array[String] rollback, Array[String] cleanup, Array[String] sync, Array[String] recovery) -> Array[String]
+    def failure_details(cause, rollback, cleanup, sync, recovery)
+      details = [cause.message]
+      details << "rollback failed: #{rollback.join('; ')}" unless rollback.empty?
+      details << "cleanup failed: #{cleanup.join('; ')}" unless cleanup.empty?
+      details << "directory sync failed: #{sync.join('; ')}" unless sync.empty?
+      details << "recovery artifacts: #{recovery.join(', ')}" unless recovery.empty?
+      details
+    end
+    # rubocop:enable Layout/LineLength
+
+    # @rbs () -> Array[String]
+    def recovery_artifacts
+      @records.filter_map do |record|
+        backup = record[:backup]
+        backup if backup && File.exist?(backup)
+      end
+    end
+
+    # @rbs () -> Array[String]
+    def rollback
+      failures = [] #: Array[String]
+      @records.reverse_each do |record|
+        rollback_record(record)
+      rescue StandardError => e
+        failures << "#{record.fetch(:target)}: #{e.message}"
+      end
+      failures
+    end
+
+    # @rbs (Hash[Symbol, Object?] record) -> void
+    def rollback_record(record)
+      target = record.fetch(:target) #: String
+      if record.fetch(:backed_up)
+        if record.fetch(:installed)
+          File.rename(record.fetch(:backup).to_s, target)
+        else
+          File.unlink(record.fetch(:backup).to_s)
+        end
+        record[:backup] = nil
+        record[:backed_up] = false
+        record[:installed] = false
+      elsif record.fetch(:installed)
+        File.unlink(target)
+        record[:installed] = false
+      end
+    end
+
+    # @rbs (preserve_backups: bool) -> Array[String]
+    def cleanup_artifacts(preserve_backups:)
+      failures = [] #: Array[String]
+      @records.each do |record|
+        paths = [record[:stage]]
+        paths << record[:backup] unless preserve_backups
+        paths.compact.each { |path| remove_artifact(path, failures) }
+      end
+      failures
+    end
+
+    # @rbs (String path, Array[String] failures) -> void
+    def remove_artifact(path, failures)
+      File.unlink(path)
+    rescue Errno::ENOENT
+      nil
+    rescue StandardError => e
+      failures << "#{path}: #{e.message}"
+    end
+
+    # @rbs () -> Array[String]
+    def sync_directories_best_effort
+      failures = [] #: Array[String]
+      @records.map { |record| record.fetch(:directory) }.uniq.sort.each do |directory|
+        File.open(directory, File::RDONLY, &:fsync)
+      rescue StandardError => e
+        failures << "#{directory}: #{e.message}"
+      end
+      failures
+    end
+  end
+end

data/lib/ibex/generation_transaction_validation.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # Canonical target, source, symlink, and lock identity checks for generation.
+  module GenerationTransactionValidation
+    # @rbs!
+    #   private def lock_path: (String) -> String
+
+    private
+
+    # Follow a final symlink while preserving the symlink path itself during publication.
+    # @rbs (String path, ?Hash[String, bool] seen, ?validate_links: bool) -> String
+    def resolved_target(path, seen = {}, validate_links: true)
+      expanded = File.expand_path(path)
+      if File.symlink?(expanded)
+        raise Errno::ELOOP, expanded if seen[expanded]
+
+        seen[expanded] = true
+        linked = File.expand_path(File.readlink(expanded), File.dirname(expanded))
+        return resolved_target(linked, seen, validate_links: validate_links)
+      end
+      return existing_target(expanded, validate_links) if File.exist?(expanded)
+
+      parent = File.realpath(File.dirname(expanded))
+      raise Errno::ENOTDIR, parent unless File.directory?(parent)
+
+      File.join(parent, File.basename(expanded))
+    end
+
+    # @rbs (String expanded, bool validate_links) -> String
+    def existing_target(expanded, validate_links)
+      target = File.realpath(expanded)
+      validate_existing_target!(target) if validate_links
+      target
+    end
+
+    # @rbs (String target) -> void
+    def validate_existing_target!(target)
+      stat = File.stat(target)
+      unless stat.file?
+        raise GenerationTransaction::Error,
+              "(generation):1:1: output target is not a regular file: #{target}"
+      end
+      return unless stat.nlink > 1
+
+      raise GenerationTransaction::Error,
+            "(generation):1:1: output target has multiple hard links: #{target}"
+    end
+
+    # @rbs () -> void
+    def validate_source_boundaries!
+      source_paths = @source_records.map(&:path)
+      @records.each do |record|
+        target = record.fetch(:target)
+        collision = source_paths.find { |source| paths_alias?(target, source) }
+        next unless collision
+
+        raise GenerationTransaction::Error,
+              "(generation):1:1: artifact target aliases generation input: #{target} (#{collision})"
+      end
+    end
+
+    # @rbs (Array[String] lock_paths) -> void
+    def validate_lock_boundaries!(lock_paths)
+      protected_paths = protected_generation_paths
+      lock_paths.each do |path|
+        if File.symlink?(path)
+          raise GenerationTransaction::Error,
+                "(generation):1:1: generation lock must not be a symlink: #{path}"
+        end
+
+        collision = protected_paths.find { |protected| paths_alias?(path, protected) }
+        next unless collision
+
+        raise GenerationTransaction::Error,
+              "(generation):1:1: generation lock aliases a protected path: #{path} (#{collision})"
+      end
+    end
+
+    # @rbs (String path, File lock) -> void
+    def validate_lock_identity!(path, lock)
+      path_stat = File.lstat(path)
+      lock_stat = lock.stat
+      unless stable_lock_identity?(path_stat, lock_stat)
+        raise GenerationTransaction::Error,
+              "(generation):1:1: generation lock identity changed while opening: #{path}"
+      end
+      return unless protected_generation_stats.any? { |stat| same_inode?(stat, lock_stat) }
+
+      raise GenerationTransaction::Error,
+            "(generation):1:1: generation lock aliases a protected inode: #{path}"
+    end
+
+    # @rbs () -> Array[String]
+    def protected_generation_paths
+      @source_records.map(&:path) + @records.map { |record| record.fetch(:target) }
+    end
+
+    # @rbs () -> Array[File::Stat]
+    def protected_generation_stats
+      protected_generation_paths.filter_map { |path| File.stat(path) if File.exist?(path) }
+    end
+
+    # @rbs (File::Stat path_stat, File::Stat lock_stat) -> bool
+    def stable_lock_identity?(path_stat, lock_stat)
+      path_stat.file? && path_stat.nlink == 1 && same_inode?(path_stat, lock_stat)
+    end
+
+    # @rbs (File::Stat left, File::Stat right) -> bool
+    def same_inode?(left, right)
+      left.dev == right.dev && left.ino == right.ino
+    end
+
+    # @rbs (String left, String right) -> bool
+    def paths_alias?(left, right)
+      return true if File.expand_path(left) == File.expand_path(right)
+      return true if portable_target_key(left) == portable_target_key(right)
+      return false unless File.exist?(left) && File.exist?(right)
+
+      File.identical?(left, right)
+    rescue SystemCallError
+      true
+    end
+
+    # Reject target names that collide on common case-insensitive or
+    # normalization-insensitive filesystems, even when the current filesystem
+    # would permit both names.
+    # @rbs (String path) -> [String, String]
+    def portable_target_key(path)
+      basename = File.basename(path)
+      folded = if basename.encoding == Encoding::UTF_8 && basename.valid_encoding?
+                 basename.unicode_normalize(:nfc).downcase(:fold).unicode_normalize(:nfc)
+               else
+                 basename.downcase
+               end
+      [File.dirname(path), folded]
+    end
+
+    # @rbs (String phase) -> void
+    def ensure_sources_stable!(phase)
+      validate_active_locks!(phase)
+      validate_current_targets!(phase)
+      return if @stability_check.call
+
+      raise GenerationTransaction::SourceChanged, "(generation):1:1: source changed #{phase}"
+    end
+
+    # @rbs (String phase) -> void
+    def validate_active_locks!(phase)
+      @locked_paths.zip(@locks).each do |path, lock|
+        next if stable_lock_identity?(File.lstat(path), lock.stat)
+
+        raise GenerationTransaction::SourceChanged,
+              "(generation):1:1: generation lock changed #{phase}: #{path}"
+      end
+    rescue SystemCallError => e
+      raise GenerationTransaction::SourceChanged,
+            "(generation):1:1: cannot revalidate generation lock #{phase}: #{e.message}"
+    end
+
+    # @rbs (String phase) -> void
+    def validate_current_targets!(phase)
+      sources = @source_records.map(&:path)
+      @records.each do |record|
+        validate_current_target!(record, sources, phase)
+      end
+    rescue SystemCallError => e
+      raise GenerationTransaction::SourceChanged,
+            "(generation):1:1: cannot revalidate artifact target #{phase}: #{e.message}"
+    end
+
+    # @rbs (Hash[Symbol, Object?] record, Array[String] sources, String phase) -> void
+    def validate_current_target!(record, sources, phase)
+      artifact = record.fetch(:artifact) #: Artifact
+      current = resolved_target(artifact.path, validate_links: false)
+      unless current == record.fetch(:target)
+        raise GenerationTransaction::SourceChanged,
+              "(generation):1:1: artifact target changed #{phase}: #{artifact.path}"
+      end
+      return unless sources.any? { |source| paths_alias?(current, source) }
+
+      raise GenerationTransaction::SourceChanged,
+            "(generation):1:1: artifact target aliases an input #{phase}: #{artifact.path}"
+    end
+
+    # @rbs () -> void
+    def validate_locked_targets!
+      current = @records.map { |record| lock_path(record.fetch(:target)) }.uniq.sort
+      return if current == @locked_paths
+
+      raise GenerationTransaction::Error,
+            "(generation):1:1: output target changed while acquiring generation locks"
+    end
+  end
+end