mountfd 0.1.0

data/lib/mountfd/attributes.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mountfd
+  module Attributes
+    VALUES = {
+      rdonly: Native::MOUNT_ATTR_RDONLY,
+      nosuid: Native::MOUNT_ATTR_NOSUID,
+      nodev: Native::MOUNT_ATTR_NODEV,
+      noexec: Native::MOUNT_ATTR_NOEXEC,
+      nodiratime: Native::MOUNT_ATTR_NODIRATIME,
+      nosymfollow: Native::MOUNT_ATTR_NOSYMFOLLOW,
+      idmap: Native::MOUNT_ATTR_IDMAP
+    }.freeze
+    ATIME = {
+      relatime: Native::MOUNT_ATTR_RELATIME,
+      noatime: Native::MOUNT_ATTR_NOATIME,
+      strictatime: Native::MOUNT_ATTR_STRICTATIME
+    }.freeze
+    PROPAGATION = {
+      unbindable: Native::MS_UNBINDABLE,
+      private: Native::MS_PRIVATE,
+      slave: Native::MS_SLAVE,
+      shared: Native::MS_SHARED
+    }.freeze
+
+    def self.build(attributes)
+      set = clr = 0
+      seen = {}
+      attributes.each do |name, value|
+        key = name.respond_to?(:to_sym) ? name.to_sym : name
+        raise ArgumentError, "duplicate mount attribute: #{name.inspect}" if seen[key]
+
+        seen[key] = true
+        if key == :atime
+          mode = value.respond_to?(:to_sym) ? value.to_sym : value
+          raise ArgumentError, "unknown atime mode: #{value.inspect}" unless ATIME.key?(mode)
+
+          clr |= Native::MOUNT_ATTR__ATIME
+          set |= ATIME.fetch(mode)
+          next
+        end
+
+        flag = VALUES.fetch(key) { raise ArgumentError, "unknown mount attribute: #{name.inspect}" }
+        value ? set |= flag : clr |= flag
+      end
+      [set, clr]
+    end
+
+    def self.flags(names)
+      return names if names.is_a?(Integer)
+
+      Array(names).reduce(0) do |flags, name|
+        key = name.respond_to?(:to_sym) ? name.to_sym : name
+        flags | VALUES.fetch(key) { raise ArgumentError, "unknown mount attribute: #{name.inspect}" }
+      end
+    end
+
+    def self.propagation(value)
+      return 0 if value.nil?
+
+      key = value.respond_to?(:to_sym) ? value.to_sym : value
+      PROPAGATION.fetch(key) { raise ArgumentError, "unknown propagation: #{value.inspect}" }
+    end
+  end
+end

data/lib/mountfd/core.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Mountfd
+  AT_FDCWD = -100
+
+  Diagnostic = Data.define(:level, :text) do
+    PREFIXES = {"e" => :error, "w" => :warning, "i" => :info}.freeze
+
+    def self.parse(raw)
+      raw.lines(chomp: true).filter_map do |line|
+        prefix, separator, text = line.partition(" ")
+        level = PREFIXES[prefix]
+        new(level || :info, level && !separator.empty? ? text : line) unless line.empty?
+      end
+    end
+
+    def to_s = "#{level}: #{text}"
+  end
+
+  class FsContext
+    attr_reader :diagnostics
+
+    def self.open(filesystem, flags: 0)
+      context = new(filesystem, flags: flags)
+      return context unless block_given?
+
+      begin
+        yield context
+      ensure
+        context.close unless context.closed?
+      end
+    end
+
+    def self.pick(path, flags: 0)
+      new(nil, handle: Native.fspick(AT_FDCWD, File.path(path), flags | Native::FSPICK_CLOEXEC))
+    end
+
+    def initialize(filesystem, flags: 0, handle: nil)
+      @handle = handle || Native.fsopen(filesystem.to_s, flags | Native::FSOPEN_CLOEXEC)
+      @diagnostics = []
+    end
+
+    def fileno = @handle.fileno
+    def closed? = @handle.closed?
+    def warnings = diagnostics.select { _1.level == :warning }
+
+    def set(key, value = nil)
+      return set_flag(key) if value.nil? || value == true
+
+      configure(Native::FSCONFIG_SET_STRING, key, value.to_s, 0)
+    end
+
+    def set_flag(key) = configure(Native::FSCONFIG_SET_FLAG, key, nil, 0)
+    def set_path(key, path, dfd: AT_FDCWD) = configure(Native::FSCONFIG_SET_PATH, key, File.path(path), dfd)
+    def set_fd(key, io) = configure(Native::FSCONFIG_SET_FD, key, nil, Mountfd.fileno(io))
+    def set_binary(key, bytes)
+      value = String(bytes)
+      configure(Native::FSCONFIG_SET_BINARY, key, value, value.bytesize)
+    end
+
+    def create!(exclusive: false)
+      if exclusive && !Mountfd.features.include?(:create_excl)
+        raise UnsupportedError, "exclusive fsconfig creation requires Linux 6.6 or newer"
+      end
+
+      command = exclusive ? Native::FSCONFIG_CMD_CREATE_EXCL : Native::FSCONFIG_CMD_CREATE
+      configure(command, nil, nil, 0)
+    end
+
+    def reconfigure! = configure(Native::FSCONFIG_CMD_RECONFIGURE, nil, nil, 0)
+
+    def mount(attrs: {})
+      attr_set, attr_clr = Attributes.build(attrs)
+      raise ArgumentError, "idmap must be applied to a detached mount with a user namespace" if
+        ((attr_set | attr_clr) & Native::MOUNT_ATTR_IDMAP).positive?
+
+      handle = with_diagnostics("fsmount", MountError) do
+        Native.fsmount(@handle, Native::FSMOUNT_CLOEXEC, attr_set)
+      end
+      DetachedMount.new(handle)
+    end
+
+    def close = @handle.close
+
+    private
+
+    def configure(command, key, value, aux)
+      with_diagnostics("fsconfig") { Native.fsconfig(@handle, command, key&.to_s, value, aux) }
+      self
+    end
+
+    def with_diagnostics(operation, error_class = ConfigError)
+      result = yield
+      drain_diagnostics
+      result
+    rescue SystemCallError => error
+      begin
+        result.close if result.respond_to?(:close)
+      rescue SystemCallError
+        nil
+      end
+      begin
+        drain_diagnostics
+      rescue SystemCallError
+        nil
+      end
+      raise error_class.new("#{operation}: #{error.message}", diagnostics), cause: error
+    end
+
+    def drain_diagnostics
+      @diagnostics.concat(Diagnostic.parse(Native.read_diagnostics(@handle)))
+    end
+  end
+
+  class DetachedMount
+    def initialize(handle)
+      @handle = handle
+      Mountfd.__send__(:track, self)
+    end
+
+    def fileno = @handle.fileno
+    def closed? = @handle.closed?
+    def discard = close
+
+    def set_attributes(set: [], clr: [], propagation: nil, idmap: nil, recursive: false)
+      flags = Native::AT_EMPTY_PATH
+      flags |= Native::AT_RECURSIVE if recursive
+      set_flags = Attributes.flags(set)
+      clear_flags = Attributes.flags(clr)
+      has_idmap = (set_flags & Native::MOUNT_ATTR_IDMAP).positive?
+      raise ArgumentError, "an idmapped mount cannot be cleared" if
+        (clear_flags & Native::MOUNT_ATTR_IDMAP).positive?
+      raise ArgumentError, "MOUNT_ATTR_IDMAP and a user namespace must be provided together" if
+        has_idmap == idmap.nil?
+
+      Native.mount_setattr(
+        @handle, "", flags, set_flags, clear_flags,
+        Attributes.propagation(propagation), idmap && Mountfd.fileno(idmap)
+      )
+      self
+    rescue SystemCallError => error
+      exception = idmap ? IdmapError : MountError
+      raise exception, "mount_setattr: #{error.message}", cause: error
+    end
+
+    def idmap!(userns) = set_attributes(set: [:idmap], idmap: userns)
+
+    def attach(path, beneath: false)
+      target = File.path(path)
+      flags = Native::MOVE_MOUNT_F_EMPTY_PATH
+      flags |= Native::MOVE_MOUNT_BENEATH if beneath
+      begin
+        Native.move_mount(@handle, "", AT_FDCWD, target, flags)
+      rescue SystemCallError => error
+        raise MountError, "move_mount: #{error.message}", cause: error
+      end
+      close
+      AttachedMount.new(target)
+    end
+
+    def close
+      @handle.close
+      nil
+    ensure
+      Mountfd.__send__(:untrack, self) if @handle.closed?
+    end
+  end
+
+  AttachedMount = Data.define(:path)
+
+  class << self
+    def supported? = Native.syscall_available?("fsopen")
+
+    def features
+      return [] unless supported?
+
+      values = [:new_mount_api]
+      values.concat([:mount_setattr, :idmap]) if Native.syscall_available?("mount_setattr")
+      values << :statmount if %w[statmount listmount].all? { Native.syscall_available?(_1) }
+      values << :move_mount_beneath if kernel_at_least?(6, 5)
+      values << :create_excl if kernel_at_least?(6, 6)
+      values
+    end
+
+    def pending_mounts = (@pending_mounts || []).reject(&:closed?).dup
+
+    def mounts(ns: nil, backend: nil)
+      selected = backend || preferred_mounts_backend(ns)
+      if selected == :statmount
+        @mounts_backend = :statmount
+        values = if ns.nil?
+                   Native.statmounts(nil)
+                 elsif ns.respond_to?(:fileno)
+                   Native.statmounts(fileno(ns))
+                 else
+                   File.open("/proc/#{Integer(ns)}/ns/mnt") { Native.statmounts(_1.fileno) }
+                 end
+        return values.map { mount_info_from_statmount(_1) }
+      end
+
+      raise ArgumentError, "backend must be :statmount or :mountinfo" unless selected == :mountinfo
+      if ns&.respond_to?(:fileno)
+        raise UnsupportedError, "mount namespace descriptors require statmount on Linux 6.11 or newer"
+      end
+
+      @mounts_backend = :mountinfo
+      pid = ns.nil? ? "self" : Integer(ns)
+      read_mountinfo(pid)
+    rescue SystemCallError, UnsupportedError
+      raise if backend == :statmount || ns&.respond_to?(:fileno)
+
+      @mounts_backend = :mountinfo
+      read_mountinfo(ns ? Integer(ns) : "self")
+    end
+
+    def mounts_backend = @mounts_backend || preferred_mounts_backend(nil)
+
+    def mount_at(path, **options)
+      target = File.expand_path(File.path(path))
+      mounts(**options).find { File.expand_path(_1.mount_point) == target }
+    end
+
+    def open_tree(path, recursive: false)
+      flags = Native::OPEN_TREE_CLONE | Native::OPEN_TREE_CLOEXEC
+      flags |= Native::AT_RECURSIVE if recursive
+      mount = DetachedMount.new(Native.open_tree(AT_FDCWD, File.path(path), flags))
+      return mount unless block_given?
+
+      begin
+        yield mount
+      ensure
+        mount.discard unless mount.closed?
+      end
+    end
+
+    def mount(source, target, type: source, options: {}, attrs: {})
+      detached = nil
+      FsContext.open(type) do |context|
+        context.set("source", source) unless source.to_s == type.to_s
+        options.each { |key, value| context.set(key, value) }
+        context.create!
+        detached = context.mount(attrs: attrs)
+        detached.attach(target)
+      end
+    rescue StandardError
+      detached&.discard unless detached&.closed?
+      raise
+    end
+
+    def bind(source, target, recursive: false, attrs: {}, idmap: nil)
+      namespace = UserNamespace.create(**idmap) if idmap.is_a?(Hash)
+      detached = open_tree(source, recursive: recursive)
+      apply_attributes(detached, attrs, recursive: recursive)
+      detached.idmap!(namespace || idmap) if idmap
+      detached.attach(target)
+    rescue StandardError
+      detached&.discard unless detached&.closed?
+      raise
+    ensure
+      namespace&.close unless namespace&.closed?
+    end
+
+    def umount(path, detach: true, force: false)
+      flags = (detach ? 2 : 0) | (force ? 1 : 0)
+      Native.umount2(File.path(path), flags)
+    end
+
+    def pivot_root(new_root, put_old) = Native.pivot_root(File.path(new_root), File.path(put_old))
+
+    def set_attributes(path, attrs: {}, propagation: nil, recursive: false)
+      set, clr = Attributes.build(attrs)
+      flags = recursive ? Native::AT_RECURSIVE : 0
+      Native.mount_setattr(
+        AT_FDCWD, File.path(path), flags, set, clr, Attributes.propagation(propagation), nil
+      )
+      nil
+    rescue SystemCallError => error
+      raise MountError, "mount_setattr: #{error.message}", cause: error
+    end
+
+    def replace(path)
+      target = File.path(path)
+      detached = yield
+      raise ArgumentError, "replace block must return a DetachedMount" unless detached.is_a?(DetachedMount)
+
+      detached.attach(target, beneath: true)
+      umount(target)
+      AttachedMount.new(target)
+    rescue StandardError
+      detached&.discard unless detached&.closed?
+      raise
+    end
+
+    def fileno(value) = value.respond_to?(:fileno) ? value.fileno : Integer(value)
+
+    private
+
+    def track(mount) = (@pending_mounts ||= []) << mount
+    def untrack(mount) = @pending_mounts&.delete(mount)
+
+    def apply_attributes(mount, attributes, recursive: false)
+      set, clr = Attributes.build(attributes)
+      mount.set_attributes(set: set, clr: clr, recursive: recursive) if (set | clr).positive?
+      mount
+    end
+
+    def preferred_mounts_backend(namespace)
+      (namespace.nil? || kernel_at_least?(6, 11)) && Native.syscall_available?("statmount") &&
+        Native.syscall_available?("listmount") ? :statmount : :mountinfo
+    end
+
+    def read_mountinfo(pid)
+      mounts = MountInfoParser.parse(File.read("/proc/#{pid}/mountinfo"))
+      mounts.reverse.uniq(&:mount_point).reverse
+    end
+
+    def mount_info_from_statmount(value)
+      options = value[:options]&.split(",") || []
+      attrs = Attributes::VALUES.filter_map do |name, flag|
+        name if (value[:attrs] & flag).positive?
+      end
+      Attributes::ATIME.each do |name, flag|
+        attrs << name if flag.positive? && (value[:attrs] & flag).positive?
+      end
+      propagation = {}
+      Attributes::PROPAGATION.each do |name, flag|
+        propagation[name] = true if (value[:propagation] & flag).positive?
+      end
+      propagation[:shared] = value[:peer_group] if value[:peer_group].positive?
+      propagation[:master] = value[:master] if value[:master].positive?
+      propagation[:propagate_from] = value[:propagate_from] if value[:propagate_from].positive?
+      MountInfo.new(
+        value[:mnt_id], value[:parent_id], value[:mnt_root], value[:mount_point],
+        value[:fs_type], value[:source], options.freeze, propagation.freeze, attrs.freeze,
+        value[:dev_major], value[:dev_minor]
+      )
+    end
+
+    def kernel_at_least?(major, minor)
+      current = Etc.uname[:release].scan(/\A(\d+)\.(\d+)/).flatten.map(&:to_i)
+      Native.linux? && (current <=> [major, minor]) >= 0
+    end
+  end
+end

data/lib/mountfd/mount_info.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Mountfd
+  MountInfo = Data.define(
+    :mnt_id, :parent_id, :mnt_root, :mount_point, :fs_type, :source,
+    :options, :propagation, :attrs, :dev_major, :dev_minor
+  ) do
+    def idmapped? = attrs.include?(:idmap) || options.include?("idmapped")
+    def readonly? = attrs.include?(:rdonly) || options.include?("ro")
+  end
+
+  module MountInfoParser
+    ESCAPE = /\\([0-3][0-7]{2})/
+    UINT32_MAX = 2**32 - 1
+    UINT64_MAX = 2**64 - 1
+
+    def self.parse(content)
+      content.b.lines.filter_map { parse_line(_1) }
+    end
+
+    def self.parse_line(line)
+      fields = line.split
+      separator = fields.index("-")
+      return unless separator && separator >= 6 && fields.length >= separator + 4
+
+      device = fields[2].split(":", -1)
+      return unless device.length == 2
+
+      mnt_id, parent_id = fields.first(2).map { Integer(_1, 10) }
+      major, minor = device.map { Integer(_1, 10) }
+      return unless mnt_id.between?(0, UINT64_MAX) && parent_id.between?(0, UINT64_MAX) &&
+        major.between?(0, UINT32_MAX) && minor.between?(0, UINT32_MAX)
+
+      mount_options = fields[5].split(",")
+      super_options = fields[separator + 3].split(",")
+      optional = fields[6...separator]
+      MountInfo.new(
+        mnt_id, parent_id, decode(fields[3]), decode(fields[4]),
+        decode(fields[separator + 1]), decode(fields[separator + 2]),
+        (mount_options + super_options).uniq.freeze, parse_propagation(optional),
+        parse_attrs(mount_options + super_options, optional), major, minor
+      )
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def self.decode(value)
+      value.gsub(ESCAPE) { Regexp.last_match(1).to_i(8).chr(Encoding::BINARY) }
+    end
+
+    def self.parse_propagation(fields)
+      propagation = fields.filter_map do |field|
+        name, value = field.split(":", 2)
+        case name
+        when "shared", "master", "propagate_from"
+          [name.to_sym, Integer(value, 10)] if value
+        when "unbindable"
+          [:unbindable, true]
+        end
+      end.to_h
+      propagation[:slave] = true if propagation.key?(:master)
+      propagation[:private] = true if propagation.empty?
+      propagation.freeze
+    end
+
+    def self.parse_attrs(options, optional)
+      names = {
+        "ro" => :rdonly, "nosuid" => :nosuid, "nodev" => :nodev,
+        "noexec" => :noexec, "nodiratime" => :nodiratime,
+        "nosymfollow" => :nosymfollow, "noatime" => :noatime,
+        "strictatime" => :strictatime
+      }
+      values = options.filter_map { names[_1] }
+      values << :idmap if optional.include?("idmapped")
+      values.uniq.freeze
+    end
+  end
+end

data/lib/mountfd/namespace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Mountfd
+  module Namespace
+    def self.reexec_user!
+      return if ENV["MOUNTFD_IN_USERNS"]
+      raise UnsupportedError, "user namespaces are unavailable on this platform" unless Native.linux?
+
+      command = begin
+        File.binread("/proc/self/cmdline").split("\0")
+      rescue Errno::EACCES, Errno::ENOENT
+        []
+      end
+      command = [RbConfig.ruby, $PROGRAM_NAME, *ARGV] if command.empty?
+      exec({"MOUNTFD_IN_USERNS" => "1"}, "unshare", "-Ur", *command)
+    end
+
+    def self.unshare_mount!(propagation: :private)
+      raise ArgumentError, "propagation must be :private or nil" unless propagation.nil? || propagation == :private
+
+      warn_unless_main_thread
+      Native.unshare(Native::CLONE_NEWNS)
+      Native.change_propagation("/", Native::MS_PRIVATE | Native::MS_REC) if propagation == :private
+      nil
+    end
+
+    def self.unshare_user!(map_root: true)
+      warn_unless_main_thread
+      Native.unshare_user(map_root)
+    end
+
+    def self.warn_unless_main_thread
+      warn("Mountfd namespace changes affect only the calling OS thread") unless Thread.current == Thread.main
+    end
+    private_class_method :warn_unless_main_thread
+  end
+end

data/lib/mountfd/user_namespace.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Mountfd
+  class UserNamespace
+    MAX_RANGES = 340
+
+    def self.create(uid: {0 => Process.uid}, gid: {0 => Process.gid}, helper: :auto)
+      uid_map = normalize(uid)
+      gid_map = normalize(gid)
+      use_helper = case helper
+                   when :auto then helpers_available? && !Process.euid.zero?
+                   when true, false then helper
+                   else raise ArgumentError, "helper must be :auto, true, or false"
+                   end
+      new(Native.user_namespace(format(uid_map), format(gid_map), use_helper))
+    rescue SystemCallError => error
+      raise IdmapError, "user namespace: #{error.message}", cause: error
+    end
+
+    def self.from_pid(pid) = from_path("/proc/#{Integer(pid)}/ns/user")
+    def self.from_path(path) = new(Native.open_handle(File.path(path)))
+
+    def self.normalize(mapping)
+      ranges = if mapping.is_a?(Hash)
+                 mapping.map do |inside, outside|
+                   if outside.is_a?(Array) && outside.length != 2
+                     raise ArgumentError, "hash mapping values must be an ID or [ID, length]"
+                   end
+                   outside, length = outside.is_a?(Array) ? outside : [outside, 1]
+                   [inside, outside, length]
+                 end
+               elsif mapping.is_a?(Array) && mapping.length == 3 && mapping.none? { _1.is_a?(Array) }
+                 [mapping]
+               else
+                 Array(mapping)
+               end
+      ranges = ranges.map do |range|
+        raise ArgumentError, "each namespace mapping must contain three integers" unless range.is_a?(Array) && range.length == 3
+
+        range.map { Integer(_1) }
+      end.sort_by(&:first)
+      raise ArgumentError, "a namespace mapping requires at least one range" if ranges.empty?
+      raise ArgumentError, "namespace mappings are limited to #{MAX_RANGES} ranges" if ranges.length > MAX_RANGES
+
+      ranges.each do |inside, outside, length|
+        raise ArgumentError, "mapping IDs must be non-negative" if inside.negative? || outside.negative?
+        raise ArgumentError, "mapping length must be positive" unless length.positive?
+        if inside + length > 2**32 || outside + length > 2**32
+          raise ArgumentError, "mapping ranges must fit unsigned 32-bit IDs"
+        end
+      end
+      validate_non_overlapping!(ranges, 0, "inside")
+      validate_non_overlapping!(ranges, 1, "outside")
+      ranges
+    end
+
+    def self.format(ranges) = ranges.map { _1.join(" ") }.join("\n") << "\n"
+
+    def self.validate_non_overlapping!(ranges, index, label)
+      sorted = ranges.sort_by { _1[index] }
+      sorted.each_cons(2) do |left, right|
+        raise ArgumentError, "overlapping #{label} mapping ranges" if left[index] + left[2] > right[index]
+      end
+    end
+    private_class_method :format, :validate_non_overlapping!
+
+    def self.helpers_available?
+      %w[newuidmap newgidmap].all? do |program|
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
+          File.executable?(File.join(directory, program))
+        end
+      end
+    end
+    private_class_method :helpers_available?
+
+    def initialize(handle)
+      @handle = handle
+    end
+
+    def fileno = @handle.fileno
+    def closed? = @handle.closed?
+    def close = @handle.close
+  end
+end

data/lib/mountfd/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mountfd
+  VERSION = "0.1.0"
+end

data/lib/mountfd.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "mountfd/version"
+
+module Mountfd
+  class Error < StandardError; end
+  class UnsupportedError < Error; end
+
+  class ConfigError < Error
+    attr_reader :diagnostics
+
+    def initialize(message, diagnostics = [])
+      @diagnostics = diagnostics
+      super([message, *diagnostics.map(&:to_s)].join("\n"))
+    end
+  end
+
+  class MountError < ConfigError; end
+  class IdmapError < Error; end
+end
+
+begin
+  require "mountfd/mountfd"
+rescue LoadError
+  require_relative "../ext/mountfd/mountfd"
+end
+
+require_relative "mountfd/attributes"
+require_relative "mountfd/user_namespace"
+require_relative "mountfd/mount_info"
+require_relative "mountfd/namespace"
+require_relative "mountfd/core"