Extend storage proposal D-Bus API

.github/workflows/ci.yml

@@ -75,7 +75,7 @@ jobs:
 
     - name: Git Checkout
       uses: actions/checkout@v2
-    
+
     - name: Install Ruby development files
       run: zypper --non-interactive install gcc gcc-c++ make openssl-devel ruby-devel npm augeas-devel
 
@@ -117,6 +117,37 @@ jobs:
     - name: Rubocop
       run: /usr/bin/rubocop.*-1.24.1
 
+  backend_doc:
+    runs-on: ubuntu-latest
+    env:
+      COVERAGE: 1
+
+    defaults:
+      run:
+        working-directory: ./service
+
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [ "tumbleweed" ]
+
+    container:
+      image: registry.opensuse.org/yast/head/containers_${{matrix.distro}}/yast-ruby
+
+    steps:
+
+    - name: Git Checkout
+      uses: actions/checkout@v2
+
+    - name: Install Ruby development files
+      run: zypper --non-interactive install gcc gcc-c++ make openssl-devel ruby-devel npm augeas-devel
+
+    - name: Install RubyGems dependencies
+      run: bundle config set --local with 'development' && bundle install
+
+    - name: Generate doc
+      run: bundle exec yardoc --fail-on-warning
+
   cli_tests:
     runs-on: ubuntu-latest
     env:

doc/dbus_api.md

@@ -113,93 +113,65 @@ Iface: o.o.YaST.Installer1.Software
 
 ## Storage
 
-### Iface: o.o.YaST.Installer1.Storage
+### org.opensuse.DInstaller.Storage1
 
-#### methods:
-
--  MarkForUse(array(o.o.YaST.Installer1.Storage.BlockDevice Device)) -> void
-    set objects for use of installation. it means erase content of that devices
-    example:
-
-      MarkForUse([disk1,disk2partition2]) -> ()
-
--  MarkForShrinking(array(o.o.YaST.Installer1.Storage.BlockDevice Device)) -> void
-    set objects to allow shrink of them. it means keep content and reduce its free space.
-    example:
+#### Methods
 
-      MarkForShrink([disk1,disk2partition2]) -> ()
+- Probe -> void
 
-#### Properties (all read only):
+- Install -> void
 
--  Drives -> array(o.o.YaST.Installer1.Storage.Drive)  # an object\_path whose object implements this interface
-    List of all disks.
-    Example:
+- Finish -> void
 
-      Drives -> [disk1, disk2]
-
--  Partitions -> array(o.o.YaST.Installer1.Storage.Partition)
-    List of all partitions.
-    Example:
-
-      Disks -> [disk1partition1, disk1partition2, disk2partition1]
-
--  DevicesToUse -> array(o.o.YaST.Installer1.Storage.BlockDevice)
-    Devices that will be fully used by installation
-    Example:
-
-      DevicesToUse -> [disk1,disk2partition2]
-
--  DevicesToShrink -> array(o.o.YaST.Installer1.Storage.BlockDevice)
-    Devices that will be shrinked to make space for installation
-    Example:
-
-      DevicesToShrink -> [disk1,disk2partition2]
-
-#### Signals:
+### org.opensuse.DInstaller.Proposal1
 
-  PropertiesChanged ( only standard one from org.freedesktop.DBus.Properties interface )
+** Making space is not covered yet**
 
-### Iface: o.o.YaST.Installer1.Storage.BlockDevice
-
-Inspired by Udisks2.Block
-
-#### Properties (all read only):
-
--  Device -> string DevPath
-    Block device name in /dev like "/dev/sda"
-
--  Size -> uint64 SizeInBytes
-    Size of devices in bytes
-
--  ReadOnly -> boolean
-    if device is read only
-
-### Iface: o.o.YaST.Installer1.Storage.Drive
-
-Inspired by Udisks2.Drive
-
-#### Properties (all read only):
-
--  Vendor -> string
-    Vendor of device or empty string if not known like "Fujitsu"
-
--  Model -> string
-    Device model or empty string if not known
-
--  Removable -> boolean
-    if device is removable like usb sticks
-
--  Partitions -> array(o.o.YaST.Installer1.Storage.Partition)
-    partitions on given drive
-
-### Iface: o.o.YaST.Installer1.Storage.Partition
-
-Inspired by Udisks2.Partition
+#### Properties
 
-#### Properties (all read only):
+- AvailableDevices -> a(ssa{sv}) (r)
+  e.g., ["/dev/sda", "/dev/sda, 8.00 GiB, USB", {}]
+
+- CandidateDevices -> as (r)
+
+- LVM -> b (r)
+
+- EncryptionPassword -> s (r)
+
+- VolumeTemplates -> aa{sv} (r)
+  Struct keys and values: see Volumes
+
+- Volumes -> aa{sv} (r)
+  Struct keys and values:
+  - DeviceType -> s
+  e.g., "partition", "lvm_lv"
+  - Optional -> b
+  - Encrypted -> b
+  - MountPoint -> s
+  - FixedSizeLimits -> b
+  - AdaptativeSizes -> b
+  - MinSize -> s
+  - MaxSize -> s
+  - FsTypes -> as
+    e.g., ["Btrfs", "XFS"]
+  - FsType -> s
+  - Snapshots -> b
+  - SnapshotsConfigurable -> b
+  - SnapshotsAffectSizes -> b
+  - VolumesWithFallbackSizes -> as
+    e.g., ["/home", "/var"]
+
+- Actions -> aa{sv} (r)
+  Struct keys and values:
+  - Text -> s (r)
+  - Subvol -> b (r)
+  - Delete -> b (r)
+
+#### Methods
+
+- Calculate(aa{sv}) -> u (0 success, 1 fail)
+  Calculates a new proposal with the given properties (see proposal properties).
 
--  Drive -> o.o.YaST.Installer1.Storage.Drive
-    where partitions live
 
 ## Users
 

service/.rubocop.yml

@@ -8,6 +8,7 @@ AllCops:
   Exclude:
     - vendor/**/*
     - lib/dinstaller/dbus/y2dir/**/*
+    - d-installer.gemspec
 
 # a D-Bus method definition may take up more line lenght than usual
 Layout/LineLength:

service/Gemfile.lock

@@ -60,6 +60,9 @@ GEM
     simplecov-html (0.12.3)
     simplecov-lcov (0.8.0)
     simplecov_json_formatter (0.1.4)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
@@ -73,6 +76,7 @@ DEPENDENCIES
   rspec (~> 3.11.0)
   simplecov (~> 0.21.2)
   simplecov-lcov (~> 0.8.0)
+  yard (~> 0.9.0)
 
 BUNDLED WITH
    2.3.3

service/bin/d-installer

@@ -54,7 +54,7 @@ end
 def start_service(name)
   general_y2dir = File.expand_path("../lib/dinstaller/dbus/y2dir", __dir__)
   module_y2dir = File.expand_path("../lib/dinstaller/dbus/y2dir/#{name}", __dir__)
-  ENV["Y2DIR"] = "#{module_y2dir}:#{general_y2dir}"
+  ENV["Y2DIR"] = [ENV["Y2DIR"], module_y2dir, general_y2dir].compact.join(":")
 
   service_runner = DInstaller::DBus::ServiceRunner.new(name, logger: logger_for(name))
   service_runner.run

service/d-installer.gemspec

@@ -40,6 +40,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.11.0"
   spec.add_development_dependency "simplecov", "~> 0.21.2"
   spec.add_development_dependency "simplecov-lcov", "~> 0.8.0"
+  spec.add_development_dependency "yard", "~>0.9.0"
   spec.add_dependency "cfa", "~> 1.0.2"
   spec.add_dependency "cfa_grub2", "~> 2.0.0"
   spec.add_dependency "cheetah", "~> 1.0.0"

service/lib/dinstaller/cockpit_manager.rb

@@ -48,7 +48,6 @@ def initialize(path: DEFAULT_PATH, file_handler: nil)
     #
     # If the given section does not exist, it returns an empty one
     #
-    # @param name [String] section name
     # @return [AugeasTree]
     def web_service
       data["WebService"] ||= CFA::AugeasTree.new
@@ -78,7 +77,7 @@ def initialize(logger, prefix: "/")
     #
     # If all arguments are nil, the configuration is not modified and the process is not restarted.
     #
-    # @param config [Hash]
+    # @param options [Hash]
     #   @option ssl [Boolean,nil] SSL is enabled
     #   @option ssl_cert [String,nil] SSL/TLS certificate URL
     #   @option ssl_key  [String,nil] SSL/TLS key URL

service/lib/dinstaller/config.rb

@@ -100,7 +100,7 @@ def copy
 
     # Returns a new {Config} with the merge of the given ones
     #
-    # @params config [Config, Hash]
+    # @param config [Config, Hash]
     # @return [Config] new Configuration with the merge of the given ones
     def merge(config)
       Config.new(simple_merge(data, config.data))

service/lib/dinstaller/config_reader.rb

@@ -66,11 +66,11 @@ def config_from_file(path = nil)
       Config.from_file(path)
     end
 
-    # Return an {Array} with the different {Config} objects read from the different locations
+    # Return an arry with the different {Config} objects read from the different locations
     #
     # TODO: handle precedence correctly
     #
-    # @returm [Array<Config>] an array with all the configurations read from the system
+    # @return [Array<Config>] an array with all the configurations read from the system
     def configs
       return @configs if @configs
 

service/lib/dinstaller/dbus/language_service.rb

@@ -41,7 +41,7 @@ class LanguageService
       # @return [::DBus::Connection]
       attr_reader :bus
 
-      # @param config [Config] Configuration object
+      # @param _config [Config] Configuration object
       # @param logger [Logger]
       def initialize(_config, logger = nil)
         @logger = logger || Logger.new($stdout)

service/lib/dinstaller/dbus/storage/manager.rb

@@ -39,7 +39,7 @@ class Manager < BaseObject
 
         # Constructor
         #
-        # @param backend [DInstaller::Software]
+        # @param backend [DInstaller::Storage::Manager]
         # @param logger [Logger]
         def initialize(backend, logger)
           super(PATH, logger: logger)