From 97bce6ca2fb8f88a4b99f3ba722d9447cb223071 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20St=C3=BCrz?= Date: Thu, 8 Jul 2021 10:44:16 +0200 Subject: [PATCH] add rdoc documentation to ruby code (#3) --- README.md | 2 +- .../opnsense_device/opnsense_device.rb | 36 ++++++++++++++ .../opnsense_firewall_alias.rb | 22 ++++++++- .../opnsense_plugin/opnsense_plugin.rb | 48 ++++++++++++++----- lib/puppet/provider/opnsense_provider.rb | 14 ++++++ lib/puppet/provider/opnsense_sensitive.rb | 2 + 6 files changed, 111 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 6f0a2d8..8d29470 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ## Table of Contents -- [Description](#description) +- [Module Description](#module-description) - [Features](#features) - [Setup](#setup) * [OPNsense firewall](#opnsense-firewall) diff --git a/lib/puppet/provider/opnsense_device/opnsense_device.rb b/lib/puppet/provider/opnsense_device/opnsense_device.rb index 997c632..b9f3f9b 100644 --- a/lib/puppet/provider/opnsense_device/opnsense_device.rb +++ b/lib/puppet/provider/opnsense_device/opnsense_device.rb @@ -7,11 +7,16 @@ # Implementation for the opnsense_device type using the Resource API. class Puppet::Provider::OpnsenseDevice::OpnsenseDevice < Puppet::Provider::OpnsenseProvider + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [Array>] filter + # @return [Array>] def get(_context, filter) device_names = get_device_names_by_filter(filter) _get_devices(device_names) end + # @param [Array>] filter + # @return [Array>, Array] def get_device_names_by_filter(filter) if filter.empty? return get_configured_devices @@ -19,6 +24,8 @@ def get_device_names_by_filter(filter) filter end + # @param [Array] device_names + # @return [Array>] def _get_devices(device_names) result = [] device_names.each do |device_name| @@ -31,6 +38,9 @@ def _get_devices(device_names) result end + # @param [String] device_name + # @param [Array>] data + # @return [Hash{Symbol->Hash}] def _create_opnsense_device(device_name, data) { ensure: 'present', @@ -44,22 +54,36 @@ def _create_opnsense_device(device_name, data) } end + # @param [String] path + # @return [Psych::Exception, nil] def _read_yaml(path) YAML.safe_load(File.read(path)) end + # @param [String] pw + # @return [Puppet::Provider::OpnsenseSensitive] def _gen_pw(pw) Puppet::Provider::OpnsenseSensitive.new(pw) end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] name + # @param [Hash] should + # @return [File] def create(_context, name, should) _write_config(name, should) end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] name + # @param [Hash] should def update(_context, name, should) _write_config(name, should) end + # @param [String] name + # @param [Hash] should + # @return [File] def _write_config(name, should) basedir = get_config_basedir _ensure_dir(basedir) @@ -75,14 +99,22 @@ def _write_config(name, should) _write_yaml(config_path, yaml_data) end + # @param [String] path + # @param [Integer] mode + # @return [Integer] def _ensure_dir(path, mode = 0o700) Dir.mkdir(path, mode) unless File.exist?(path) end + # @param [Puppet::Provider::OpnsenseSensitive] sensitive + # @return [String] def _extract_pw(sensitive) sensitive.unwrap end + # @param [String] path + # @param [Hash] data + # @param [Integer] mode def _write_yaml(path, data, mode = 0o600) File.open(path, 'w') do |file| file.write(YAML.dump(data)) @@ -90,11 +122,15 @@ def _write_yaml(path, data, mode = 0o600) end end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] name def delete(_context, name) path = get_config_path(name) FileUtils.rm(path, force: true) end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [Hash] resources def canonicalize(_context, resources) resources.each do |r| if r.key?(:api_secret) && r[:api_secret].is_a?(Puppet::Pops::Types::PSensitiveType::Sensitive) diff --git a/lib/puppet/provider/opnsense_firewall_alias/opnsense_firewall_alias.rb b/lib/puppet/provider/opnsense_firewall_alias/opnsense_firewall_alias.rb index 728c0cb..9aa5c6b 100644 --- a/lib/puppet/provider/opnsense_firewall_alias/opnsense_firewall_alias.rb +++ b/lib/puppet/provider/opnsense_firewall_alias/opnsense_firewall_alias.rb @@ -5,14 +5,18 @@ # Implementation for the opnsense_firewall_alias type using the Resource API. class Puppet::Provider::OpnsenseFirewallAlias::OpnsenseFirewallAlias < Puppet::Provider::OpnsenseProvider + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [Array>] filter + # @return [Array>] def get(_context, filter) device_names = get_device_names_by_filter(filter) _get_firewall_aliases_from_devices(device_names) end + # @param [Array] devices + # @return [Array>] def _get_firewall_aliases_from_devices(devices) result = [] - devices.each do |device| aliases = _aliases_list(device) aliases.each do |fw_alias| @@ -34,23 +38,36 @@ def _get_firewall_aliases_from_devices(devices) result end + # @param [String] device_name + # @return [Array] def _aliases_list(device_name) json_output = opn_cli_base_cmd(device_name, ['firewall', 'alias', 'list', '-o', 'json']) JSON.parse(json_output) end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] _name + # @param [Hash] should + # @return [Puppet::Util::Execution::ProcessOutput] def create(_context, _name, should) args = _get_command_args('create', should) device_name = should[:device].to_s opn_cli_base_cmd(device_name, args) end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] _name + # @param [Hash] should + # @return [Puppet::Util::Execution::ProcessOutput] def update(_context, _name, should) args = _get_command_args('update', should) device_name = should[:device].to_s opn_cli_base_cmd(device_name, args) end + # @param [Integer] mode + # @param [Hash] should + # @return [Array] def _get_command_args(mode, should) args = ['firewall', 'alias', mode, should[:name]] args.push('-t', should[:type]) @@ -66,6 +83,9 @@ def _get_command_args(mode, should) args end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] name + # @return [Puppet::Util::Execution::ProcessOutput] def delete(_context, name) alias_name = name.fetch(:name).to_s device_name = name.fetch(:device).to_s diff --git a/lib/puppet/provider/opnsense_plugin/opnsense_plugin.rb b/lib/puppet/provider/opnsense_plugin/opnsense_plugin.rb index 6fd2702..859d769 100644 --- a/lib/puppet/provider/opnsense_plugin/opnsense_plugin.rb +++ b/lib/puppet/provider/opnsense_plugin/opnsense_plugin.rb @@ -4,15 +4,20 @@ # Implementation for the opnsense_plugin type using the Resource API. class Puppet::Provider::OpnsensePlugin::OpnsensePlugin < Puppet::Provider::OpnsenseProvider + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [Array>] filter + # @return [Array>] def get(_context, filter) device_names = get_device_names_by_filter(filter) - get_plugins_from_devices(device_names) + _get_plugins_from_devices(device_names) end - def get_plugins_from_devices(devices) + # @param [Array] devices + # @return [Array>] + def _get_plugins_from_devices(devices) result = [] devices.each do |device| - plugins = plugin_list(device) + plugins = _plugin_list(device) plugins.each do |plugin| result.push( title: plugin + '@' + device, @@ -25,30 +30,51 @@ def get_plugins_from_devices(devices) result end - def plugin_list(device_name) + # @param [String] device_name + # @return [Array] + def _plugin_list(device_name) result = opn_cli_base_cmd(device_name, ['plugin', 'installed', '-c', 'name']) result.split("\n") end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] _name + # @param [Hash] should + # @return [Puppet::Util::Execution::ProcessOutput] def create(_context, _name, should) - plugin_install(should[:device].to_s, should[:name].to_s) + _plugin_install(should[:device].to_s, should[:name].to_s) end - def plugin_install(device_name, plugin_name) - opn_cli_base_cmd(device_name, ['plugin', 'install', plugin_name.to_s]) + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] _name + # @param [Hash] should + # @return [Puppet::Util::Execution::ProcessOutput] + def update(_context, _name, should) + _plugin_install(should[:device].to_s, should[:name].to_s) end - def update(_context, _name, should) - plugin_install(should[:device].to_s, should[:name].to_s) + # @param [String] device_name + # @param [String] plugin_name + # @return [Puppet::Util::Execution::ProcessOutput] + def _plugin_install(device_name, plugin_name) + opn_cli_base_cmd(device_name, ['plugin', 'install', plugin_name.to_s]) end + # @param [Puppet::ResourceApi::BaseContext] _context + # @param [String] name + # @return [Puppet::Util::Execution::ProcessOutput] def delete(_context, name) plugin_name = name.fetch(:name).to_s device = name.fetch(:device).to_s - plugin_uninstall(device, plugin_name) + _plugin_uninstall(device, plugin_name) end - def plugin_uninstall(device_name, plugin_name) + # @param [String] device_name + # @param [String] plugin_name + # @return [Puppet::Util::Execution::ProcessOutput] + def _plugin_uninstall(device_name, plugin_name) opn_cli_base_cmd(device_name, ['plugin', 'uninstall', plugin_name.to_s]) end + + private :_get_plugins_from_devices, :_plugin_list, :_plugin_install, :_plugin_uninstall end diff --git a/lib/puppet/provider/opnsense_provider.rb b/lib/puppet/provider/opnsense_provider.rb index 55284e6..d9e6da9 100644 --- a/lib/puppet/provider/opnsense_provider.rb +++ b/lib/puppet/provider/opnsense_provider.rb @@ -3,12 +3,16 @@ # A base provider for all opnsense providers class Puppet::Provider::OpnsenseProvider < Puppet::ResourceApi::SimpleProvider + # @return [void] def initialize @config_basedir = '~/.puppet-opnsense' @config_suffix = '-config.yaml' super end + # @param [String] device_name + # @param [Array] args + # @return [Puppet::Util::Execution::ProcessOutput] def opn_cli_base_cmd(device_name, *args) config_path = get_config_path(device_name) args.unshift( @@ -19,10 +23,13 @@ def opn_cli_base_cmd(device_name, *args) Puppet::Util::Execution.execute(args, failonfail: true, custom_environment: { 'LC_ALL' => 'en_US.utf8' }) end + # @param [String] device_name + # @return [String] def get_config_path(device_name) File.join(get_config_basedir.to_s, "#{File.basename(device_name)}#{_get_suffix}") end + # @return [Array] def get_configured_devices devices = [] Dir.glob(_get_config_glob_pattern).each do |path| @@ -32,18 +39,23 @@ def get_configured_devices devices end + # @return [String] def _get_config_glob_pattern "#{get_config_basedir}/*#{_get_suffix}" end + # @return [String] def _get_suffix @config_suffix end + # @return [String] def get_config_basedir File.expand_path(@config_basedir) end + # @param [String, Integer, Boolean] value + # @return [FalseClass, TrueClass] def bool_from_value(value) case value when true, 'true', 1, '1' then @@ -55,6 +67,8 @@ def bool_from_value(value) end end + # @param [Array>] filter + # @return [Array] def get_device_names_by_filter(filter) filter.empty? ? get_configured_devices : filter.map { |item| item[:device] }.compact.uniq end diff --git a/lib/puppet/provider/opnsense_sensitive.rb b/lib/puppet/provider/opnsense_sensitive.rb index cfaf8b8..33b41d4 100644 --- a/lib/puppet/provider/opnsense_sensitive.rb +++ b/lib/puppet/provider/opnsense_sensitive.rb @@ -1,6 +1,8 @@ # A Puppet Language type that makes the OpnsenseSensitive Type comparable # class Puppet::Provider::OpnsenseSensitive < Puppet::Pops::Types::PSensitiveType::Sensitive + # @param [Puppet::Pops::Types::PSensitiveType::Sensitive] other + # @return [TrueClass] def ==(other) return true if other.is_a?(Puppet::Pops::Types::PSensitiveType::Sensitive) && unwrap == other.unwrap end