vagrant-xapi 0.0.1 → 1.0.0

data/lib/vagrant-xapi/services/disks.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "base"
+require_relative "disk_image"
+require_relative "lookup"
+require_relative "image_upload"
+require_relative "box_source"
+
+module VagrantPlugins
+  module Xapi
+    module Services
+      # config.vm.disk support: grow the primary disk, add named disks, import
+      # disk images, attach ISOs (local upload or from an ISO SR), and remove
+      # disks that disappeared from the Vagrantfile.
+      class Disks
+        include Helpers
+
+        TWO_TIB = 2 * 1024**4
+        MIB = 1024**2
+        CLOUD_INIT_NAME = "vagrant-cloud_init-disk"
+        DESCRIPTION = "vagrant-xapi disk"
+
+        # @param default_sr [String, nil] provider config `sr`
+        # @param converter [#call, nil] qcow2 -> VHD converter (qemu-img)
+        # @param digest_cache [DigestCache, nil] avoids re-hashing large ISOs
+        #   on every boot
+        def initialize(ctx, default_sr: nil, converter: nil, digest_cache: nil)
+          @ctx = ctx
+          @client = ctx.client
+          @lookup = Lookup.new(ctx)
+          @default_sr = default_sr
+          @upload = ImageUpload.new(ctx, converter: converter)
+          @digest_cache = digest_cache
+        end
+
+        # @param disks [Array] Vagrant disk configs (type, name, size, primary,
+        #   file, provider_config)
+        # @return [Hash] { disk: [{uuid:, name:}], dvd: [...], floppy: [] }
+        def configure(vm, disks)
+          result = { disk: [], floppy: [], dvd: [] }
+          return result if disks.empty?
+
+          @ctx.ui&.info(:configuring_disks)
+          vm_uuid = @client.call("VM.get_uuid", vm)
+          disks.each do |disk|
+            case disk.type
+            when :disk
+              entry = disk.primary ? configure_primary(vm, disk) : configure_named(vm, vm_uuid, disk)
+              result[:disk] << entry if entry
+            when :dvd
+              entry = configure_dvd(vm, vm_uuid, disk)
+              result[:dvd] << entry if entry
+            when :floppy
+              raise Error.new(:floppy_unsupported, name: disk.name.to_s)
+            end
+          end
+          result
+        end
+
+        # @param meta [Hash] disk_meta from the last configure ("disk"/"dvd")
+        def cleanup(vm, disks, meta)
+          vm_uuid = @client.call("VM.get_uuid", vm)
+          names = disks.map { |d| d.name.to_s }
+          %w[disk dvd].each do |kind|
+            Array(meta[kind]).each do |entry|
+              next if entry["primary"]
+              next if names.include?(entry["name"].to_s)
+
+              @ctx.ui&.warn(:disk_removed, name: entry["name"])
+              remove_disk(vm, vm_uuid, entry["uuid"])
+            end
+          end
+        end
+
+        # Attaches ISOs from ISO SRs (provider option `isos`) as CD drives and
+        # detaches the ones this plugin attached that are no longer listed.
+        # The ISO VDIs themselves are never destroyed.
+        def sync_isos(vm, names)
+          names = Array(names).map(&:to_s)
+          attached = {}
+          vbds_of(vm).each do |vbd, rec|
+            iso = (rec["other_config"] || {})[Marking::ISO]
+            next unless iso
+
+            if names.include?(iso) && !attached.key?(iso)
+              attached[iso] = vbd
+            else
+              unplug_if_running(vm, vbd, rec)
+              ignore_missing { @client.call("VBD.destroy", vbd) }
+            end
+          end
+          (names - attached.keys).each do |iso|
+            vbd = attach(vm, @lookup.iso_vdi(iso), "CD")
+            set_oc("VBD", vbd, Marking::ISO, iso)
+          end
+        end
+
+        private
+
+        def unplug_if_running(vm, vbd, rec)
+          return unless rec["currently_attached"] && @client.call("VM.get_power_state", vm) == "Running"
+
+          @client.call("VBD.unplug", vbd)
+        rescue Api::XapiError => e
+          raise Error.new(:disk_unplug_failed, name: rec["userdevice"].to_s, reason: e.code)
+        end
+
+        def configure_primary(vm, disk)
+          vbd, rec = vbds_of(vm).find { |_ref, r| r["userdevice"].to_s == "0" && r["type"] == "Disk" }
+          raise Error.new(:primary_disk_missing) unless vbd
+
+          vdi = rec["VDI"]
+          resize(vm, vdi, disk.size, disk.name) if disk.size
+          { uuid: @client.call("VDI.get_uuid", vdi), name: disk.name.to_s, primary: true }
+        end
+
+        def configure_named(vm, vm_uuid, disk)
+          name = disk.name.to_s
+          raise Error.new(:disk_name_required) if name.empty?
+
+          existing = find_owned(vm, vm_uuid, name, "Disk")
+          if existing
+            resize(vm, existing, disk.size, name) if disk.size
+            return { uuid: @client.call("VDI.get_uuid", existing), name: name }
+          end
+
+          sr = sr_for(disk)
+          vdi = if disk.file
+                  import_image(sr, disk.file, name)
+                else
+                  warn_large(disk.size, name)
+                  create_vdi(sr, name, disk.size.to_i, description: DESCRIPTION)
+                end
+          mark_vdi(vdi, vm_uuid, name)
+          attach(vm, vdi, "Disk")
+          { uuid: @client.call("VDI.get_uuid", vdi), name: name }
+        end
+
+        def configure_dvd(vm, vm_uuid, disk)
+          name = disk.name.to_s
+          file = disk.file.to_s
+          raise Error.new(:dvd_file_missing, name: name) if file.empty? || !File.file?(file)
+
+          sha = @digest_cache ? @digest_cache.digest(file) : Digest::SHA256.file(file).hexdigest
+          existing = find_owned(vm, vm_uuid, name, nil)
+          if existing
+            if @client.call("VDI.get_other_config", existing)[Marking::CONTENT_SHA256] == sha
+              return { uuid: @client.call("VDI.get_uuid", existing), name: name }
+            end
+
+            @ctx.ui&.detail(:replacing_iso, name: name)
+            remove_disk(vm, vm_uuid, @client.call("VDI.get_uuid", existing))
+          end
+
+          sr = sr_for(disk)
+          size = ((File.size(file) + MIB - 1) / MIB) * MIB
+          vdi = create_vdi(sr, name, size, description: DESCRIPTION)
+          begin
+            vdi = @upload.upload(vdi, file, "raw", label: "vagrant-xapi upload iso")
+          rescue Exception # rubocop:disable Lint/RescueException
+            ignore_missing { @client.call("VDI.destroy", vdi) }
+            raise
+          end
+          mark_vdi(vdi, vm_uuid, name)
+          set_oc("VDI", vdi, Marking::CONTENT_SHA256, sha)
+          set_oc("VDI", vdi, Marking::CLOUD_INIT, "true") if name == CLOUD_INIT_NAME
+          attach_cd(vm, vdi, name)
+          { uuid: @client.call("VDI.get_uuid", vdi), name: name }
+        end
+
+        def find_owned(vm, vm_uuid, name, type)
+          vbds_of(vm).each do |_vbd, rec|
+            next if null_ref?(rec["VDI"])
+            next if type && rec["type"] != type
+
+            oc = ignore_missing { @client.call("VDI.get_other_config", rec["VDI"]) } || {}
+            return rec["VDI"] if oc[Marking::DISK_NAME] == name && oc[Marking::OWNER_VM] == vm_uuid
+          end
+          nil
+        end
+
+        def resize(vm, vdi, size, name)
+          want = size.to_i
+          have = @client.call("VDI.get_virtual_size", vdi).to_i
+          return if want == have || want.zero?
+          raise Error.new(:disk_shrink, name: name.to_s, have: have, want: want) if want < have
+
+          warn_large(want, name)
+          unless @client.call("VM.get_power_state", vm) == "Halted"
+            raise Error.new(:resize_needs_halt, name: name.to_s)
+          end
+
+          @ctx.ui&.detail(:resizing_disk, name: name.to_s, size: want)
+          @client.call("VDI.resize", vdi, want)
+        end
+
+        def import_image(sr, file, name)
+          raise Error.new(:disk_image_missing, path: file.to_s) unless File.file?(file.to_s)
+
+          info = DiskImage.inspect_file(file.to_s)
+          warn_large(info.virtual_size, name)
+          vdi = create_vdi(sr, name, info.virtual_size, description: DESCRIPTION)
+          begin
+            vdi = @upload.upload(vdi, file.to_s, info.format, label: "vagrant-xapi import disk")
+          rescue Exception # rubocop:disable Lint/RescueException
+            ignore_missing { @client.call("VDI.destroy", vdi) }
+            raise
+          end
+          vdi
+        end
+
+        def mark_vdi(vdi, vm_uuid, name)
+          set_oc("VDI", vdi, Marking::OWNER_VM, vm_uuid)
+          set_oc("VDI", vdi, Marking::DISK_NAME, name)
+        end
+
+        def attach(vm, vdi, type, mode: type == "CD" ? "RO" : "RW")
+          vbd = create_vbd(vm, vdi, mode: mode, type: type)
+          @client.call("VBD.plug", vbd) if @client.call("VM.get_power_state", vm) == "Running"
+          vbd
+        end
+
+        # An uploaded ISO lives on a normal SR. Attach it as a CD; if XAPI
+        # refuses that, or all CD slots are taken, fall back to a read-only
+        # disk (cloud-init NoCloud finds its "cidata" volume on any block
+        # device).
+        def attach_cd(vm, vdi, name)
+          attach(vm, vdi, "CD")
+        rescue Api::XapiError => e
+          @ctx.logger&.info("attaching ISO as CD failed (#{e.code}); attaching as read-only disk")
+          attach(vm, vdi, "Disk", mode: "RO")
+        rescue Error => e
+          raise unless e.key == :no_free_cd_slot
+
+          @ctx.ui&.warn(:dvd_as_disk, name: name, in_use: e.params[:in_use]) unless name == CLOUD_INIT_NAME
+          attach(vm, vdi, "Disk", mode: "RO")
+        end
+
+        def remove_disk(vm, vm_uuid, vdi_uuid)
+          vdi = ignore_missing { @client.call("VDI.get_by_uuid", vdi_uuid.to_s) }
+          return unless vdi
+
+          running = @client.call("VM.get_power_state", vm) == "Running"
+          vbds_of(vm).each do |vbd, rec|
+            next unless rec["VDI"] == vdi
+
+            if running && rec["currently_attached"]
+              begin
+                @client.call("VBD.unplug", vbd)
+              rescue Api::XapiError => e
+                raise Error.new(:disk_unplug_failed, name: vdi_uuid.to_s, reason: e.code)
+              end
+            end
+            ignore_missing { @client.call("VBD.destroy", vbd) }
+          end
+
+          oc = @client.call("VDI.get_other_config", vdi)
+          # Only destroy what we created; VDIs from an ISO SR stay.
+          ignore_missing { @client.call("VDI.destroy", vdi) } if Marking.ours?(oc, Marking::OWNER_VM, vm_uuid)
+        end
+
+        def sr_for(disk)
+          name = provider_option(disk, :sr) || @default_sr
+          @lookup.sr(name)
+        end
+
+        def provider_option(disk, key)
+          pc = disk.provider_config || {}
+          scoped = pc[:xapi] || pc["xapi"] || {}
+          scoped[key] || scoped[key.to_s] || pc[:"xapi__#{key}"] || pc["xapi__#{key}"]
+        end
+
+        def warn_large(size, name)
+          @ctx.ui&.warn(:disk_over_2tib, name: name.to_s) if size.to_i > TWO_TIB
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-xapi/services/exporter.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "base"
+require_relative "lookup"
+
+module VagrantPlugins
+  module Xapi
+    module Services
+      # Exports a halted VM as the content of an `xapi` box: XVA (all disks)
+      # or the first disk as VHD or qcow2. Works on a temporary clone that is
+      # stripped of everything that belongs to this pool.
+      class Exporter
+        include Helpers
+
+        FORMATS = %w[xva vhd qcow2].freeze
+
+        def initialize(ctx)
+          @ctx = ctx
+          @client = ctx.client
+        end
+
+        # @return [Hash] the box metadata written to metadata.json
+        def export(vm, directory, format:)
+          format = format.to_s
+          raise Error.new(:package_format_unsupported, image_format: format) unless FORMATS.include?(format)
+
+          unless @client.call("VM.get_power_state", vm) == "Halted"
+            raise Error.new(:package_needs_halt)
+          end
+
+          media_devices = iso_userdevices(vm)
+          name = "vagrant-xapi package #{@client.call("VM.get_name_label", vm)}"
+          @ctx.ui&.info(:package_cloning)
+          clone = @ctx.run_task("VM.clone", vm, name, label: "clone for package").ref
+          begin
+            strip(clone, media_devices, vm)
+            dest = File.join(directory.to_s, "box.#{format}")
+            @ctx.ui&.info(:package_exporting, image_format: format)
+            lookup = Lookup.new(@ctx)
+            if format == "xva"
+              download("/export", { "uuid" => @client.call("VM.get_uuid", clone), "use_compression" => "zstd" },
+                       dest, lookup.transfer_host_for_vm(clone))
+            else
+              vdi = boot_vdi(clone)
+              begin
+                download("/export_raw_vdi", { "vdi" => vdi, "format" => format }, dest,
+                         lookup.transfer_host_for_sr(@client.call("VDI.get_SR", vdi)))
+              rescue Api::HttpError => e
+                raise unless e.status.between?(400, 499)
+
+                raise Error.new(:export_format_refused, image_format: format, status: e.status)
+              end
+            end
+          ensure
+            destroy_clone(clone, vbds_of(vm).map { |_v, r| r["VDI"] })
+          end
+
+          metadata = { "provider" => "xapi", "format" => format, "architecture" => "amd64" }
+          File.write(File.join(directory.to_s, "metadata.json"), JSON.generate(metadata))
+          metadata
+        end
+
+        private
+
+        def download(path, query, dest, host)
+          @client.http.download(path, query, dest, host: host,
+                                progress: @ctx.progress_proc(:downloading, file: File.basename(dest)),
+                                cancel: @ctx.cancel, task_label: "export #{File.basename(dest)}")
+          @ctx.ui&.clear_progress
+        end
+
+        # Userdevices of CDs and uploaded ISOs (incl. cloud-init) on the VM.
+        def iso_userdevices(vm)
+          vbds_of(vm).filter_map do |_vbd, rec|
+            next rec["userdevice"] if rec["type"] == "CD"
+            next if null_ref?(rec["VDI"])
+
+            oc = ignore_missing { @client.call("VDI.get_other_config", rec["VDI"]) } || {}
+            rec["userdevice"] if oc.key?(Marking::CLOUD_INIT) || oc.key?(Marking::CONTENT_SHA256)
+          end
+        end
+
+        def strip(clone, media_devices, original)
+          original_vdis = vbds_of(original).map { |_v, r| r["VDI"] }
+          vbds_of(clone).each do |vbd, rec|
+            next unless media_devices.include?(rec["userdevice"])
+
+            @client.call("VBD.destroy", vbd)
+            vdi = rec["VDI"]
+            ignore_missing { @client.call("VDI.destroy", vdi) } unless null_ref?(vdi) || original_vdis.include?(vdi)
+          end
+          @client.call("VM.get_VIFs", clone).each { |vif| @client.call("VIF.destroy", vif) }
+          @client.call("VM.get_other_config", clone).each_key do |key|
+            remove_oc("VM", clone, key) if key.start_with?(Marking::PREFIX)
+          end
+          begin
+            @client.call("VM.remove_tags", clone, Marking::TAG)
+          rescue Api::XapiError
+            nil
+          end
+          disk_vdis(clone).each do |vdi|
+            @client.call("VDI.get_other_config", vdi).each_key do |key|
+              remove_oc("VDI", vdi, key) if key.start_with?(Marking::PREFIX)
+            end
+          end
+        end
+
+        def boot_vdi(vm)
+          _vbd, rec = vbds_of(vm).find { |_v, r| r["type"] == "Disk" && r["userdevice"].to_s == "0" }
+          rec ||= vbds_of(vm).find { |_v, r| r["type"] == "Disk" }&.last
+          raise Error.new(:primary_disk_missing) unless rec
+
+          rec["VDI"]
+        end
+
+        def destroy_clone(clone, keep)
+          vdis = (ignore_missing { disk_vdis(clone) } || []) - keep
+          ignore_missing { @client.call("VM.destroy", clone) }
+          vdis.each { |vdi| ignore_missing { @client.call("VDI.destroy", vdi) } }
+        rescue Api::Error => e
+          @ctx.logger&.warn("could not remove package clone: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-xapi/services/file_diff.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "set"
+
+require_relative "base"
+
+module VagrantPlugins
+  module Xapi
+    module Services
+      # Plain comparison of two file listings, for `vagrant xapi diff`.
+      #
+      # A listing is the output of GNU find with PRINTF, run in the root of
+      # the tree on "." or on "./<path>": per file eight NUL-terminated fields
+      # (type, mode, uid, gid, size, mtime, link target, path). Paths are
+      # bytes as the guest wrote them; they are kept as binary strings and
+      # only escaped for display. find has no field for the device numbers of
+      # a device node, so those are compared by type, mode and owner only.
+      module FileDiff
+        PRINTF = '%y\0%m\0%U\0%G\0%s\0%T@\0%l\0%p\0'
+        FIELDS = 8
+
+        # tree: index of the tree (file system) the file was listed in;
+        # rel: path relative to that tree, as the guest knows it.
+        Entry = Struct.new(:type, :mode, :uid, :gid, :size, :mtime, :target, :tree, :rel)
+
+        # kind: :added, :removed, :changed (content, possibly also metadata),
+        # :metadata (mode or owner only), :type (e.g. file became symlink).
+        # unreadable: the content of one side could not be read.
+        Change = Struct.new(:kind, :path, :from, :to, :unreadable, keyword_init: true)
+
+        # Paths left out unless --no-default-excludes: they change on every
+        # boot, hold caches or logs, or (/usr/src) hold kernel headers and
+        # module sources that every kernel update replaces.
+        DEFAULT_EXCLUDES = %w[/tmp /var/tmp /var/cache /var/log /var/lib/systemd/random-seed /usr/src].freeze
+
+        TYPE_NAMES = { "f" => "file", "d" => "directory", "l" => "symlink", "b" => "block_device",
+                       "c" => "char_device", "p" => "fifo", "s" => "socket" }.freeze
+
+        # Which paths to compare. A path is compared when it lies below one of
+        # `paths` (all, when empty) and neither it nor one of its parent
+        # directories matches an exclude pattern (a shell glob over the whole
+        # path; `*` also matches `/`). A pattern that does not start with `/`
+        # matches at any depth, as in rsync: `node_modules` leaves out every
+        # file or directory of that name, `app/cache` every .../app/cache.
+        # `internal` paths (the run's own temporary directory) are always
+        # left out.
+        class Filter
+          GLOB = /[*?\[{]/.freeze
+
+          # --path directories, normalized
+          attr_reader :paths
+
+          def initialize(paths: [], excludes: [], internal: [])
+            @options = { paths: paths, excludes: excludes, internal: internal }
+            @paths = paths.map { |p| FileDiff.normalize(p) }
+            literal, globs = excludes.map { |p| FileDiff.normalize(p) }.partition { |p| !GLOB.match?(p) }
+            # At any depth: a relative literal matches the end of a parent
+            # path, a relative glob gets "*/" before it.
+            relative, @literal = literal.partition { |p| !p.start_with?("/") }
+            @relative = relative.map { |p| "/#{p}".b }
+            @globs = globs.map { |g| g.start_with?("/") ? g : "*/#{g}".b }
+            @internal = internal.map { |p| FileDiff.normalize(p) }
+          end
+
+          # The same filter that also leaves out these paths.
+          def with_internal(*paths)
+            self.class.new(**@options, internal: @options[:internal] + paths.compact)
+          end
+
+          def include?(path)
+            return false if @internal.any? { |i| FileDiff.below?(path, i) }
+            return false unless @paths.empty? || @paths.any? { |p| FileDiff.below?(path, p) }
+
+            !excluded?(path)
+          end
+
+          private
+
+          def excluded?(path)
+            return true if @literal.any? { |p| FileDiff.below?(path, p) }
+            return false if @globs.empty? && @relative.empty?
+
+            FileDiff.ancestors(path).any? do |a|
+              @relative.any? { |r| a.end_with?(r) } ||
+                @globs.any? { |g| File.fnmatch?(g, a, File::FNM_DOTMATCH | File::FNM_EXTGLOB) }
+            end
+          end
+        end
+
+        module_function
+
+        # @param data [String] listing as written by find
+        # @param mountpoint [String] where the tree belongs in the comparison
+        # @param tree [Integer] index of the tree
+        # @param into [Hash] entries are added to this hash
+        # @param hidden [Array<String>] mount points below the tree's: what is
+        #   below them is left out (the running guest cannot see it either)
+        # @return [Hash{String => Entry}] full path => entry
+        def parse(data, mountpoint, tree, into = {}, hidden: [])
+          data = data.to_s.b
+          # Every field ends with NUL: a listing cut off inside its last path
+          # still has whole groups of fields, but no NUL at the end.
+          raise Error.new(:diff_listing_invalid) unless data.empty? || data.end_with?("\0")
+
+          fields = data.split("\0", -1)
+          fields.pop
+          raise Error.new(:diff_listing_invalid) unless (fields.size % FIELDS).zero?
+
+          prefix = normalize(mountpoint)
+          hidden = hidden.map { |h| normalize(h) }
+          fields.each_slice(FIELDS) do |type, mode, uid, gid, size, mtime, target, found|
+            # "." is the root of the tree: its mode and owner belong to the
+            # mount point's path, which the tree above leaves out.
+            rel = found == "." ? "." : found.delete_prefix("./")
+            path = rel == "." ? prefix : join(prefix, rel)
+            # A mount point and what is below it belong to another tree; the
+            # entry of the mount point itself differs per side (the mounted
+            # root live, the empty directory below it in a snapshot).
+            next if hidden.any? { |h| path == h || path.start_with?("#{h}/") }
+
+            into[path] = Entry.new(type, mode, uid.to_i, gid.to_i, size.to_i, mtime,
+                                   type == "l" ? target : nil, tree, rel)
+          end
+          into
+        end
+
+        # Regular files of the same size whose content the quick check cannot
+        # tell: a different modification time, or every one with checksum.
+        # @return [Array<String>]
+        def hash_candidates(from, to, checksum: false)
+          from.filter_map do |path, a|
+            b = to[path]
+            next unless b && a.type == "f" && b.type == "f" && a.size == b.size
+            next unless checksum || a.mtime != b.mtime
+
+            path
+          end
+        end
+
+        # @param hashed [Set<String>] paths whose content was hashed
+        # @param hashes_from, hashes_to [Hash{String => String}] path => SHA-256
+        # @return [Array<Change>] sorted by path
+        def compare(from, to, hashed: Set.new, hashes_from: {}, hashes_to: {})
+          changes = []
+          from.each do |path, a|
+            b = to[path]
+            if b.nil?
+              changes << Change.new(kind: :removed, path: path, from: a)
+            else
+              change = compare_entry(path, a, b, hashed, hashes_from, hashes_to)
+              changes << change if change
+            end
+          end
+          to.each { |path, b| changes << Change.new(kind: :added, path: path, to: b) unless from.key?(path) }
+          changes.sort_by(&:path)
+        end
+
+        def compare_entry(path, a, b, hashed, hashes_from, hashes_to)
+          return Change.new(kind: :type, path: path, from: a, to: b) if a.type != b.type
+
+          unreadable = false
+          content = case a.type
+                    when "f"
+                      if a.size != b.size
+                        true
+                      elsif hashed.include?(path)
+                        ha = hashes_from[path]
+                        hb = hashes_to[path]
+                        unreadable = ha.nil? || hb.nil?
+                        unreadable || ha != hb
+                      else
+                        false
+                      end
+                    when "l" then a.target != b.target
+                    else false
+                    end
+          metadata = a.mode != b.mode || a.uid != b.uid || a.gid != b.gid
+          return nil unless content || metadata
+
+          Change.new(kind: content ? :changed : :metadata, path: path, from: a, to: b,
+                     unreadable: unreadable ? true : nil)
+        end
+
+        # Guest bytes for a terminal or JSON: valid UTF-8 without control,
+        # format (zero-width, bidirectional, soft hyphen, BOM) or line and
+        # paragraph separator characters, which could hide or rewrite what the
+        # user sees. Escapes are unambiguous: \xHH is an ASCII control or a
+        # byte that is not UTF-8, \u{H} a character, \\ a backslash.
+        def escape(value)
+          value.to_s.dup.force_encoding(Encoding::UTF_8).each_char.map do |ch|
+            if !ch.valid_encoding?
+              ch.bytes.map { |byte| format("\\x%02X", byte) }.join
+            elsif ch == "\\"
+              "\\\\"
+            elsif ch.match?(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/)
+              ch.ord < 0x80 ? format("\\x%02X", ch.ord) : format("\\u{%X}", ch.ord)
+            else
+              ch
+            end
+          end.join
+        end
+
+        def mode(entry)
+          format("%04o", entry.mode.to_i(8))
+        end
+
+        def owner(entry)
+          "#{entry.uid}:#{entry.gid}"
+        end
+
+        # Squeezes slashes and drops a trailing one. In an absolute path "."
+        # and ".." are resolved lexically: the paths of a listing never
+        # contain them, so `--path /etc/./nginx` means /etc/nginx.
+        def normalize(path)
+          path = path.to_s.b
+          path = path.squeeze("/")
+          if path.start_with?("/") && path.match?(%r{(?:\A|/)\.\.?(?:/|\z)}n)
+            parts = []
+            path.split("/").each do |part|
+              next if part.empty? || part == "."
+
+              part == ".." ? parts.pop : parts << part
+            end
+            path = "/#{parts.join("/")}".b
+          end
+          path.length > 1 ? path.chomp("/") : path
+        end
+
+        def join(prefix, rel)
+          prefix == "/" ? "/#{rel}".b : "#{prefix}/#{rel}".b
+        end
+
+        def below?(path, dir)
+          dir == "/" || path == dir || path.start_with?("#{dir}/")
+        end
+
+        # The path and its parent directories, without "/".
+        def ancestors(path)
+          list = [path]
+          while (i = path.rindex("/")) && i.positive?
+            path = path[0, i]
+            list << path
+          end
+          list
+        end
+      end
+    end
+  end
+end