bwrap 1.0.0.pre.beta1 → 1.1.0.pre.rc1

data/lib/bwrap/config.rb

@@ -18,8 +18,45 @@ require_relative "config/features"
 #
 # @todo Add some documentation about syntax where necessary, like for #binaries_from.
 class Bwrap::Config
+  # Array of audio schemes usable inside chroot.
+  #
+  # Currently supports:
+  #   - :pulseaudio
+  #
+  attr_accessor :audio
+
+  # Set to `true` if command given to {Bwrap::Bwrap#run} is expected to
+  # be inside sandbox, and not bound from host.
+  #
+  # @return [Boolean] `true` if executed command is inside sandbox
+  attr_accessor :command_inside_root
+
+  attr_accessor :extra_executables
+
+  # TODO: IIRC this doesn’t match the reality any more. So write correct documentation.
+  #
+  # Causes libraries required by the executable given to {Bwrap#run} to be
+  # mounted inside sandbox.
+  #
+  # Often it is enough to use this flag instead of binding all system libraries
+  # using {#libdir_mounts=}
+  #
+  # @return [Boolean] true if Linux library loaders are mounted inside chroot
+  attr_accessor :full_system_mounts
+
   attr_accessor :hostname
 
+  # Set to true if basic system directories, like /usr/lib and /usr/lib64,
+  # should be bound inside chroot.
+  #
+  # /usr/bin can be mounted using {Config#binaries_from=}.
+  #
+  # Often it is enough to use {#full_system_mounts=} instead of binding all
+  # system libraries using this flag.
+  #
+  # @return [Boolean] true if libdirs are mounted to the chroot
+  attr_accessor :libdir_mounts
+
   # What should be used as /etc/machine_id file.
   #
   # If not specified, no /etc/machine_id handling is done.
@@ -34,6 +71,9 @@ class Bwrap::Config
   #   Given file as bound as /etc/machine_id.
   attr_accessor :machine_id
 
+  # @return [Boolean] true if network should be shared from host.
+  attr_accessor :share_net
+
   # Name of the user inside chroot.
   #
   # This is optional and defaults to no user.
@@ -45,46 +85,23 @@ class Bwrap::Config
   # @return [Boolean] Whether Xorg specific binds are used.
   attr_accessor :xorg_application
 
-  # Array of audio schemes usable inside chroot.
-  #
-  # Currently supports:
-  #   - :pulseaudio
-  #
-  attr_accessor :audio
-
-  # @return [Boolean] true if network should be shared from host.
-  attr_accessor :share_net
-
-  # Causes libraries required by the executable given to {Bwrap#run} to be
-  # mounted inside sandbox.
-  #
-  # Often it is enough to use this flag instead of binding all system libraries
-  # using {#libdir_mounts=}
+  # Array of directories to be bind mounted in sandbox.
   #
-  # @return [Boolean] true if Linux library loaders are mounted inside chroot
-  attr_accessor :full_system_mounts
-
-  # Set to true if basic system directories, like /usr/lib and /usr/lib64,
-  # should be bound inside chroot.
+  # Given paths are also added to PATH environment variable inside sandbox.
   #
-  # /usr/bin can be mounted using {Config#binaries_from=}.
+  # @hint At least on SUSE, many executables are symlinks to /etc/alternatives/*,
+  #   which in turn symlinks to versioned executable under the same bindir.
+  #   To use these executables, /etc/alternatives should also be bound:
   #
-  # Often it is enough to use {#full_system_mounts=} instead of binding all
-  # system libraries using this flag.
+  #       config.ro_binds["/etc/alternatives"] = "/etc/alternatives"
   #
-  # @return [Boolean] true if libdirs are mounted to the chroot
-  attr_accessor :libdir_mounts
+  # @return [Array] Paths to directories where binaries are looked from.
+  attr_reader :binaries_from
 
-  # Set to `true` if command given to {Bwrap::Bwrap#run} is expected to
-  # be inside sandbox, and not bound from host.
+  # Paths to be added to sandbox instance’s PATH environment variable.
   #
-  # @return [Boolean] `true` if executed command is inside sandbox
-  attr_accessor :command_inside_root
-
-  attr_accessor :extra_executables
-
-  # Array of directories to be bind mounted and used to construct PATH environment variable.
-  attr_reader :binaries_from
+  # @see #add_env_path
+  attr_reader :env_paths
 
   # TODO: Document this.
   # TODO: I wonder if this should just be removed. I don’t know, this is a bit ...
@@ -116,16 +133,12 @@ class Bwrap::Config
   #   @param dir Path to temporary directory
   attr_reader :tmpdir
 
-  # Paths to be added to sandbox instance’s PATH environment variable.
-  #
-  # @see #add_env_path
-  attr_reader :env_paths
-
   def initialize
-    @binaries_from = []
-    @tmpdir = Dir.tmpdir
     @audio = []
+    @binaries_from = []
     @env_paths = []
+    @ro_binds = {}
+    @tmpdir = Dir.tmpdir
   end
 
   def binaries_from= array

data/lib/bwrap/execution/exceptions.rb

@@ -7,6 +7,18 @@ module Bwrap::Execution
 
   # Signifies that command execution has failed.
   class ExecutionFailed < CommandError
+    # The command that was executed.
+    attr_reader :command
+
+    # Output of the command.
+    attr_reader :output
+
+    def initialize msg, command:, output:
+      @command = command
+      @output = output
+
+      super msg
+    end
   end
 
   # Thrown if given command was not found.

data/lib/bwrap/execution/execute.rb

@@ -63,13 +63,17 @@ class Bwrap::Execution::Execute
   end
 
   # Checks whether execution failed and acts accordingly.
-  def self.handle_execution_fail fail:, error:, output:
-    return unless fail and !$CHILD_STATUS.success?
+  def self.handle_execution_fail fail:, error:, output:, command:
+    return unless fail and !execution_success?
 
     if error == :show and !output.empty?
       Bwrap::Output.warn_output "Command failed with output:\n“#{output}”"
     end
-    raise Bwrap::Execution::ExecutionFailed, "Command execution failed.", caller
+
+    exception = Bwrap::Execution::ExecutionFailed.new "Command execution failed",
+                                                      command: command,
+                                                      output: output
+    raise exception, caller
   end
 
   # @note It makes sense for caller to just return if wait has been set and not check output.
@@ -101,6 +105,13 @@ class Bwrap::Execution::Execute
                                "to add “self.prepend_rootcmd(command, rootcmd:)” method."
   end
 
+  # A wrapper to get status of an execution.
+  #
+  # Mainly here so test implementation is easier.
+  private_class_method def self.execution_success?
+    $CHILD_STATUS.success?
+  end
+
   # Used by `#handle_logging`.
   private_class_method def self.calculate_log_command command
     return command.dup unless command.respond_to?(:join)

data/lib/bwrap/execution/execution.rb

@@ -61,7 +61,7 @@ module Bwrap::Execution
     end
 
     # If command is string, splat operator (the *) does not do anything. If array, it expand the arguments.
-    # This causes spawning work correctly, as that’s how spawn() expects to have the argu
+    # This causes spawning work correctly, as that’s how spawn() expects to have the arguments.
     pid = spawn(env, *command, err: [ :child, :out ], out: Execute.w, unsetenv_others: clear_env)
     output = Execute.finish_execution(log: log, wait: wait, direct_output: direct_output)
     return pid unless wait
@@ -71,7 +71,7 @@ module Bwrap::Execution
     @last_status = $CHILD_STATUS
 
     output = Execute.process_output output: output
-    Execute.handle_execution_fail fail: fail, error: error, output: output
+    Execute.handle_execution_fail fail: fail, error: error, output: output, command: command
     output
   ensure
     Execute.clean_variables
@@ -91,14 +91,14 @@ module Bwrap::Execution
   # execute commands.
   #
   # @see .do_execute .do_execute for documentation of argument syntax
-  private def execute *args
+  private def execute *args, **kwargs
     # Mangle proper location to error message.
-    if args.last.is_a? Hash
-      args.last[:log_callback] = 3
+    if kwargs.is_a? Hash
+      kwargs[:log_callback] = 3
     else
-      args << { log_callback: 3 }
+      kwargs = { log_callback: 3 }
     end
-    Bwrap::Execution.do_execute(*args)
+    Bwrap::Execution.do_execute(*args, **kwargs)
   end
 
   # Same as ::execute, but uses log: false to avoid unnecessary output when we’re just getting a
@@ -106,7 +106,7 @@ module Bwrap::Execution
   #
   # Defaults to fail: false, since when one just wants to get the value, there is not that much
   # need to unconditionally die if getting bad exit code.
-  private def execvalue *args, fail: false, rootcmd: nil, env: {}
+  private def execvalue *args, fail: false, log: false, **kwargs
     # This logging handling is a bit of duplication from execute(), but to be extra safe, it is duplicated.
     # The debug message contents will always be evaluated, so can just do it like this.
     log_command = args[0].respond_to?(:join) && args[0].join(" ") || args[0]
@@ -121,7 +121,7 @@ module Bwrap::Execution
       return
     end
     trace "Execvaluing “#{log_command}” at #{caller_locations(1, 1)[0]}"
-    execute(*args, fail: fail, log: false, rootcmd: rootcmd, env: env)
+    execute(*args, fail: fail, log: log, **kwargs)
   end
 
   private def exec_success?

data/lib/bwrap/execution/path.rb

@@ -20,7 +20,7 @@ module Bwrap::Execution::Path
     #
     # @yield Command appended to each path in PATH environment variable
     # @yieldparam path [String] Full path to executable
-    def self.each_env_path command, env_path_var: ENV["PATH"]
+    def self.each_env_path command, env_path_var: ENV.fetch("PATH", nil)
       exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [ "" ]
 
       env_path_var.split(File::PATH_SEPARATOR).each do |env_path|
@@ -39,7 +39,7 @@ module Bwrap::Execution::Path
   # @param command [String] executable to be resolved
   # @param env_path_var [String] PATH environment variable as string.
   #   Defaults to `ENV["PATH"]`
-  private def command_available? command, env_path_var: ENV["PATH"]
+  private def command_available? command, env_path_var: ENV.fetch("PATH", nil)
     # Special handling for absolute paths.
     path = Pathname.new command
     if path.absolute?
@@ -60,7 +60,7 @@ module Bwrap::Execution::Path
   # Returns path to given executable.
   #
   # @param (see #command_available?)
-  private def which command, fail: true, env_path_var: ENV["PATH"]
+  private def which command, fail: true, env_path_var: ENV.fetch("PATH", nil)
     # Special handling for absolute paths.
     path = Pathname.new command
     if path.absolute?

data/lib/bwrap/execution.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "bwrap_module"
+
 # Declare Execution module here so Bwrap::Execution module is
 # already declared for Execution module classes, to avoid
 # a circular dependency.

data/lib/bwrap/output/levels.rb

@@ -8,7 +8,8 @@ class Bwrap::Output::Levels
 
   @@_verbose = false
   @@_debug = false
-  @@_trace = ENV["BWRAP_TRACE"] && true || false
+  @@_trace = ENV.fetch("BWRAP_TRACE", nil) && true || false
+  @@_quiet = false
 
   # @see Bwrap::Output#verbose?
   def self.verbose?
@@ -25,8 +26,18 @@ class Bwrap::Output::Levels
     @@_trace
   end
 
+  # @see Bwrap::Output##quiet?
+  def self.quiet?
+    @@_quiet
+  end
+
   # Takes hash of options received from Optimist and checks output related flags.
   def self.handle_output_options options
+    if options[:quiet] or options[:silent]
+      quiet!
+      return
+    end
+
     # Set output level flags to true or false, if it was given.
     unless options[:trace].nil?
       @@_verbose = options[:trace]
@@ -64,6 +75,18 @@ class Bwrap::Output::Levels
     out
   end
 
+  # Formats given string and outputs it.
+  #
+  # @return formatted string
+  def self.info_print_formatted str, log_callback: 1
+    # TODO: Maybe have different color for NOTICE than for INFO?
+    out = "#{Bwrap::Output::Colors.color(130, 230, 130, bold: true)}[NOTICE]#{Bwrap::Output::Colors.stopcolor} #{str}"
+    out = append_caller out, log_callback: (log_callback + 1)
+    puts out
+
+    out
+  end
+
   # Formats given string and outputs it.
   #
   # @return formatted string
@@ -98,9 +121,16 @@ class Bwrap::Output::Levels
   # Appends caller information to given output.
   #
   # Used by *_print_formatted methods.
-  def self.append_caller out, log_callback: 1
+  private_class_method def self.append_caller out, log_callback: 1
     out = "#{out} (called at #{caller_locations(log_callback, 1)[0]})" if @@_trace
     out
   end
-  private_class_method :append_caller
+
+  # Sets variables so that no extra output is shown.
+  private_class_method def self.quiet!
+    @@_verbose = false
+    @@_debug = false
+    @@_trace = false
+    @@_quiet = true
+  end
 end

data/lib/bwrap/output/log.rb

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
-# force_encoding modifies string, so can’t freeze strings.
-
 # Logging methods.
+#
+# @note One should require "bwrap/output" instead of this file directly, even
+#   if using only methods from this class.
+#
+#   This is because Bwrap::Output module would be missing, or there could be
+#   a circular dependency, which is always bad, even if Ruby would break it for you.
 class Bwrap::Output::Log
   @@log_file = nil
 
@@ -13,11 +17,17 @@ class Bwrap::Output::Log
 
   # Writes given string to log.
   def self.write_to_log str
+    # Guard against invalid input.
+    return unless str.respond_to? :force_encoding
+
     @@log_file&.write str.dup.force_encoding("UTF-8")
   end
 
   # Writes given string to log.
   def self.puts_to_log str
+    # Guard against invalid input.
+    return unless str.respond_to? :force_encoding
+
     @@log_file&.puts str.dup.force_encoding("UTF-8")
   end
 
@@ -29,6 +39,10 @@ class Bwrap::Output::Log
 
   # Starts logging to given file.
   def self.log_to_file log_path
+    unless File.writable? log_path
+      warn "Given log file #{log_path} is not writable by current user."
+      return
+    end
     log_file = File.open log_path, "w"
 
     # In default mode, log messages disappears as Ruby’s own buffer gets full.

data/lib/bwrap/output/output_impl.rb

@@ -3,6 +3,7 @@
 # Have variables like $CHILD_STATUS which is alias of $?.
 require "English"
 
+require "bwrap/bwrap_module"
 require "bwrap/execution/labels"
 
 require_relative "levels"
@@ -31,6 +32,8 @@ require_relative "log"
 # When using {Bwrap::Bwrap}, {Bwrap::Bwrap#parse_command_line_arguments}
 # causes output levels to be set if relevant CLI arguments have been
 # given. TODO: Add documentation about CLI args somewhere. Maybe README?
+#
+# TODO: Add new method info() which can then be silenced using --quiet or --silent.
 module Bwrap::Output
   # @see #verbose?
   def self.verbose?
@@ -42,6 +45,12 @@ module Bwrap::Output
     Bwrap::Output::Levels.debug?
   end
 
+  # @see #quiet?
+  # @see #info
+  def self.quiet?
+    Bwrap::Output::Levels.quiet?
+  end
+
   # @see #trace?
   def self.trace?
     Bwrap::Output::Levels.trace?
@@ -88,6 +97,18 @@ module Bwrap::Output
     Bwrap::Output::Log.puts_to_log out || str
   end
 
+  # Handler used by #info to output given string.
+  def self.info_output str, raw: false, log_callback: 1
+    return if quiet?
+
+    if raw
+      print str
+    else
+      out = Bwrap::Output::Levels.info_print_formatted str, log_callback: (log_callback + 1)
+    end
+    Bwrap::Output::Log.puts_to_log out || str
+  end
+
   # Handler used by #warn to output given string.
   def self.warn_output str, raw: false, log_callback: 1
     if raw
@@ -113,6 +134,13 @@ module Bwrap::Output
     exit exit_code
   end
 
+  # @see #info
+  #
+  # @return true if --quiet or --silent has been passed, false if not.
+  private def quiet?
+    Bwrap::Output::Levels.quiet?
+  end
+
   # @return true if --verbose, --debug or --trace has been passed, false if not.
   private def verbose?
     Bwrap::Output::Levels.verbose?
@@ -160,6 +188,33 @@ module Bwrap::Output
     Bwrap::Output.verb_output(str, raw: raw, log_callback: 2)
   end
 
+  # Outputs given string if info flag has been set.
+  #
+  # This is meant for notices, and the log will be labeled with
+  # [NOTICE].
+  #
+  # Output flags can be set with {.handle_output_options}.
+  #
+  # == Implementation hint
+  #
+  # Usually implementing --quiet and/or --silent flag
+  # to control these messages (and all other output) may make
+  # sense.
+  #
+  # That way it would be possible to have some important
+  # informational messages that should be shown, but for script
+  # usage, those could be muted.
+  #
+  # Warning messages are meant to be shown always. Error messages
+  # will always be printed, as execution is halted after the
+  # error message has been printed.
+  #
+  # @param str String to be outputted
+  # @param raw [Boolean] If true, disables output formatting
+  private def info str, raw: false
+    Bwrap::Output.info_output(str, raw: raw, log_callback: 2)
+  end
+
   # Outputs given string to `$stderr`.
   #
   # @param str String to be outputted

data/lib/bwrap/output.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "bwrap_module"
+
 # Declare Output module here so Bwrap::Output module is
 # already declared for Output module classes, to avoid
 # a circular dependency.

data/lib/bwrap/version.rb

@@ -2,7 +2,7 @@
 
 module Bwrap
   # Current version of bwrap.
-  VERSION = "1.0.0-beta1"
+  VERSION = "1.1.0-rc1"
 end
 
 require "deep-cover" if ENV["DEEP_COVER"]

data/lib/bwrap.rb

@@ -1,28 +1,3 @@
 # frozen_string_literal: true
 
-require "bwrap/bwrap"
-
-# ruby-bwrap provides easy-to-use interface to run complex programs in sandboxes created with
-# {https://github.com/containers/bubblewrap bubblewrap}.
-#
-# To run a program inside bubblewrap, a wrapper executable can be created. For example:
-#
-#     require "bwrap"
-#
-#     config = Bwrap::Config.new
-#     config.user = "dummy_user"
-#     config.full_system_mounts = true
-#     config.binaries_from = %w{
-#       /bin
-#       /usr/bin
-#     }
-#
-#     bwrap = Bwrap::Bwrap.new config
-#     bwrap.parse_command_line_arguments
-#     bwrap.run "/bin/true"
-#
-# There also are few generic utilities, {Bwrap::Output} for handling output of scripts and
-# {Bwrap::Execution} to run executables.
-module Bwrap
-  # Empty module.
-end
+require "bwrap/bwrap"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bwrap
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta1
+  version: 1.1.0.pre.rc1
 platform: ruby
 authors:
 - Samu Voutilainen
@@ -34,7 +34,7 @@ cert_chain:
   X4ioQwEn1/9tHs19VO1CLF58451HgEo1BXd7eWLmV1V5cqw0YWok1ly4L/Su/Phf
   MRxVMHiVAqY=
   -----END CERTIFICATE-----
-date: 2021-12-12 00:00:00.000000000 Z
+date: 2022-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -92,20 +92,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
 - !ruby/object:Gem::Dependency
   name: rspec-expectations
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: '3.11'
 description: For now this is tailored to my needs, so this may or may not be of any
   use.
 email:
@@ -121,16 +149,23 @@ files:
 - lib/bwrap/args/args.rb
 - lib/bwrap/args/bind.rb
 - lib/bwrap/args/bind/library.rb
+- lib/bwrap/args/bind/library/ruby_binds.rb
 - lib/bwrap/args/bind/mime.rb
 - lib/bwrap/args/construct.rb
 - lib/bwrap/args/environment.rb
 - lib/bwrap/args/features.rb
+- lib/bwrap/args/features/binds_base.rb
+- lib/bwrap/args/features/ruby_binds.rb
 - lib/bwrap/args/library.rb
 - lib/bwrap/args/machine_id.rb
 - lib/bwrap/args/mount.rb
+- lib/bwrap/args/network.rb
 - lib/bwrap/bwrap.rb
+- lib/bwrap/bwrap_module.rb
 - lib/bwrap/config.rb
 - lib/bwrap/config/features.rb
+- lib/bwrap/config/features/base.rb
+- lib/bwrap/config/features/ruby.rb
 - lib/bwrap/execution.rb
 - lib/bwrap/execution/exceptions.rb
 - lib/bwrap/execution/execute.rb