Major refactor of PFSenseModuleBase supporting generate_module pfsensible module generator

.gitignore

@@ -108,3 +108,6 @@ venv.bak/
 
 # ansible-galaxy package
 *.tar.gz
+
+# vi
+*.swp

changelogs/fragments/pfsense_alias-add-url.yml

@@ -0,0 +1,2 @@
+minor_changes:
+ - pfsense_alias - Add `url` parameter and deprecate using `address` for `urltable` and `urltable_ports` types.

misc/pfsense_module.py.j2

@@ -0,0 +1,233 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) {{ year }}, {{ author_name }} <{{ author_email }}>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+DOCUMENTATION = r'''
+---
+module: pfsense_{{ module_name }}
+
+short_description: Manage pfSense {{ module_name }}s
+
+version_added: "0.7.0"
+
+description:
+  - Manage pfSense {{ module_name }}s.{{ ' This requires the pfSense ' ~ package ~ ' package to be installed.' if is_package else '' }}
+
+options:
+{% if not is_config %}
+  {{ name_param }}:
+    description: The {{ name_param }} of the {{ module_name }}.
+    required: true
+    type: str
+  state:
+    description: State in which to leave the {{ module_name }}.
+    default: present
+    choices: ['present', 'absent']
+    type: str
+{% endif %}
+{% for name, param in params.items() %}
+  {{ name }}:
+    description: {{ "'" if ':' in param['description'] else '' }}{{ param['description'] | default('') }}{{ "'" if ':' in param['description'] else '' }}
+{% if 'choices' in param %}
+    choices: {{ param['choices'] }}
+{% endif %}
+    type: {{ param['type'] | default('') }}
+{% if param['type'] == 'list' %}
+    elements: 'str'
+{% endif %}
+{% endfor %}
+
+author: {{ author_name }} (@{{ author_handle }})
+'''
+
+EXAMPLES = r'''
+- name: {{ 'Configure' if is_config else 'Add myitem' }} {{ module_name }}
+  pfsensible.{{ package }}.pfsense_{{ module_name }}:
+{% if not is_config %}
+    {{ name_param }}: myitem
+{% endif %}
+{% for name, param in params.items() %}
+{% if param['example'] is defined %}
+{% if param['type'] == 'list' %}
+    {{ name }}:
+      - {{ param['example'] }}
+      - {{ param['example2'] | default('another item') }}
+{% else %}
+    {{ name }}: {{ param['example'] }}
+{% endif %}
+{% else %}
+    {{ name }}: {% if param['type'] == 'bool' %}false{% elif param['type'] == 'list' %}{% if 'choices' in param %}['{{ param['choices'][0:1] | join("', '") }}']{% else %}['item']{% endif %}{% elif param['type'] == 'str' %}{{ param['choices'][0] if 'choices' in param else '' }}{% endif %}
+
+{% endif %}
+{% endfor %}
+{% if not is_config %}
+    state: present
+
+- name: Remove myitem {{ module_name }}
+  pfsensible.{{ package }}.pfsense_{{ module_name }}:
+    {{ name_param }}: myitem
+    state: absent
+{% endif %}
+'''
+RETURN = r'''
+commands:
+    description: the set of commands that would be pushed to the remote device (if pfSense had a CLI).
+    returned: always
+    type: list
+{% if is_config %}
+    sample: ["update {{ module_name }} set ..."]
+{% else %}
+    sample: ["create {{ module_name }} 'myitem'", "update {{ module_name }} 'myitem' set ...", "delete {{ module_name }} 'myitem'"]
+{% endif %}
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+{% if is_config %}
+from ansible_collections.pfsensible.core.plugins.module_utils.module_config_base import PFSenseModuleConfigBase
+{% else %}
+from ansible_collections.pfsensible.core.plugins.module_utils.module_base import PFSenseModuleBase
+{% endif %}
+{% if args_imports %}
+from ansible_collections.pfsensible.core.plugins.module_utils.arg_route import {{ args_imports | sort | join(', ') }}
+{% endif %}
+
+# TODO -Change to name of module, extend for needed parameters
+# TODO -Keep either this or the next compact version of {{ module_name | upper() }}_ARGUMENT_SPEC
+{{ module_name | upper() }}_ARGUMENT_SPEC = {
+{% if not is_config %}
+    # Only {{ name_param }} should be required here - othewise you cannot remove an item with just '{{ name_param }}'
+    # Required arguments for creation should be noted in {{ module_name | upper() }}_REQUIRED_IF = ['state', 'present', ...] below
+    '{{ name_param }}': {'required': True, 'type': 'str'},
+    'state': {
+        'type': 'str',
+        'default': 'present',
+        'choices': ['present', 'absent']
+    },
+{% endif %}
+{% for param in params %}
+    '{{ param }}': {
+{% if 'choices' in params[param] %}
+        'choices': {{ params[param]['choices'] }},
+{% endif %}
+        'type': '{{ params[param]['type'] | default('') }}',
+    },
+{% endfor %}
+}
+
+# Compact style
+{{ module_name | upper() }}_ARGUMENT_SPEC = dict(
+{% if not is_config %}
+    # Only {{ name_param }} should be required here - othewise you cannot remove an item with just '{{ name_param }}'
+    # Required arguments for creation should be noted in {{ module_name | upper() }}_REQUIRED_IF = ['state', 'present', ...] below
+    {{ name_param }}=dict(required=True, type='str'),
+    state=dict(type='str', default='present', choices=['present', 'absent']),
+{% endif %}
+{% for param in params %}
+    {{ param }}=dict(type='{{ params[param]['type'] | default('') }}'{% if 'choices' in params[param] %}, choices={{ params[param]['choices'] }},{% endif %}),
+{% endfor %}
+)
+
+# TODO - check for validity - what parameters are actually required when creating a new {{ module_name }}?
+{{ module_name | upper() }}_REQUIRED_IF = [
+{% if not is_config %}
+{% if module_type %}
+    ['state', 'present', ['type']],
+    ['type', '{{ params['type']['example'] }}', ['{{ params | dict2items | rejectattr('key', 'equalto', 'type') | selectattr('value.required', 'defined') | rejectattr('value.default', 'defined') | map(attribute='key') | join("', '") }}']],
+{% else %}
+    ['state', 'present', ['{{ params | dict2items | selectattr('value.required', 'defined') | rejectattr('value.default', 'defined') | map(attribute='key') | join("', '") }}']],
+{% endif %}
+{% endif %}
+]
+
+{% if params_xml_only %}
+# TODO - check this for validity and matching module argument
+{{ module_name | upper() }}_MAP_PARAM = [
+{% for param in params_xml_only %}
+    ('ARG', '{{ param }}'),
+{% endfor %}
+]
+
+{% endif %}
+# TODO - review this for clues for input validation.  Search for functions in the below require_once files in /etc and /usr/local/pfSense/include
+PHP_VALIDATION = r'''
+{{ php_requires }}
+
+{{ php_save }}
+'''
+
+# TODO - add validation and parsing methods for parameters that require it
+{{ module_name | upper() }}_ARG_ROUTE = dict(
+{% set param_items = ((params | dict2items | selectattr('value.parse', 'defined') | list) + (params | dict2items | selectattr('value.validate', 'defined')) | list) | unique %}
+{% if param_items %}
+{% for param_item in param_items %}
+    {{ param_item.key }}=dict({% if param_item.value.parse is defined %}parse={{ param_item.value.parse }},{% endif %}{% if param_item.value.validate is defined %}validate={{ param_item.value.validate }},{% endif %}),
+{% endfor %}
+{% else %}
+# TODO - these are just examples
+    authorizedkeys=dict(parse=p2o_ssh_pub_key),
+    password=dict(validate=validate_password),
+{% endif %}
+)
+
+{% if not is_config %}
+# TODO - check for validity - what are default values when creating a new {{ module_name }}
+{{ module_name | upper() }}_CREATE_DEFAULT = dict(
+{% for item in params | dict2items | selectattr('value.default', 'defined') %}
+    {{ item.key }}='{{ item.value.default | default('VALUE') }}',
+{% endfor %}
+{% for param in params_xml_only %}
+    {{ param }}='{{ params[param]['example'] | default('VALUE') }}',
+{% endfor %}
+)
+
+{% endif %}
+{% if is_package %}
+{{ module_name | upper() }}_PHP_COMMAND_SET = r'''
+require_once("{{ package }}.inc");
+{{ package }}_sync_package();
+'''
+
+{% elif 'filter.inc' in php_requires %}
+{{ module_name | upper() }}_PHP_COMMAND_SET = r'''
+require_once("filter.inc");
+if (filter_configure() == 0) { clear_subsystem_dirty('{{ php_subsystem }}'); }
+'''
+
+{% endif %}
+
+class PFSense{{ module_name | capitalize() }}Module({{ module_base }}):
+    """ module managing pfsense {{ module_name }}s """
+
+    ##############################
+    # unit tests
+    #
+    # Must be class method for unit test usage
+    @staticmethod
+    def get_argument_spec():
+        """ return argument spec """
+        return {{ module_name | upper() }}_ARGUMENT_SPEC
+
+    def __init__(self, module, pfsense=None):
+        super(PFSense{{ module_name | capitalize() }}Module, self).__init__(module, pfsense, {{ 'package=\'' ~ package ~ '\', ' if is_package else ''}}root='{{ module_root }}', node='{{ module_node }}', key='{{ module_key }}'{{ ', update_php=' ~ module_name | upper() ~ '_PHP_COMMAND_SET' if 'filter.inc' in php_requires else '' }},
+                                                arg_route={{ module_name | upper() }}_ARG_ROUTE{% if params_xml_only %}, map_param={{ module_name | upper() }}_MAP_PARAM{% endif %}{% if not is_config %}, create_default={{ module_name | upper() }}_CREATE_DEFAULT{% endif %})
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec={{ module_name | upper() }}_ARGUMENT_SPEC,
+        required_if={{ module_name | upper() }}_REQUIRED_IF,
+        supports_check_mode=True)
+
+    pfmodule = PFSense{{ module_name | capitalize() }}Module(module)
+    # Pass params for testing framework
+    pfmodule.run(module.params)
+    pfmodule.commit_changes()
+
+
+if __name__ == '__main__':
+    main()

plugins/module_utils/__impl/checks.py

@@ -15,7 +15,8 @@ def check_name(self, name, objtype):
 
     msg = None
     if len(name) >= 32 or len(re.findall(r'(^_*$|^\d*$|[^a-zA-Z0-9_])', name)) > 0:
-        msg = "The {0} name must be less than 32 characters long, may not consist of only numbers, may not consist of only underscores, ".format(objtype)
+        msg = "The {0} name '{1}' must be less than 32 characters long, may not consist of only numbers, may not consist of only underscores, ".format(
+            objtype, name)
         msg += "and may only contain the following characters: a-z, A-Z, 0-9, _"
     elif name in ["port", "pass"]:
         msg = "The {0} name must not be either of the reserved words 'port' or 'pass'".format(objtype)