From bd6dec4406f1e9e9c821b0ca5cd6615592c86dac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Wed, 19 Sep 2018 00:36:51 +0200 Subject: [PATCH 01/10] Add matrix notification module --- lib/ansible/modules/notification/matrix.py | 121 +++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 lib/ansible/modules/notification/matrix.py diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py new file mode 100644 index 00000000000000..91f815eacf65f7 --- /dev/null +++ b/lib/ansible/modules/notification/matrix.py @@ -0,0 +1,121 @@ +#!/usr/bin/python + +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'community' +} + +DOCUMENTATION = ''' +--- +module: matrix + +short_description: This module can send notifications to matrix rooms + +version_added: "2.7" + +description: + - "This module can send html formatted notifications to matrix rooms" + +options: + msg_plain: + description: + - This is the plain text form of the message to send to matrix, usually markdown + required: true + msg_html: + description: + - This is the html form of the message to send to matrix + required: true + room_id: + description: + - The id of the room to send the notification to + required: true + hs_url: + description: + - The URL of the homeserver, where the CS-API is reachable + required: true + token: + description: + - The authentication token for the API call. If provided, user_id and password are not required + user_id: + description: + - The user id of the user + password: + description: + - The password to log in with + + +author: + - Jan Christian Grünhage (@jcgruenhage) +''' + +EXAMPLES = ''' +- name: Send matrix notification with token + matrix: + msg_plain: "**hello world**" + msg_html: "hello world" + room_id: "!12345678:server.tld" + hs_url: "https://matrix.org" + token: "{{ matrix_auth_token }}" + +- name: Send matrix notification with user_id and password + matrix: + msg_plain: "**hello world**" + msg_html: "hello world" + room_id: "!12345678:server.tld" + hs_url: "https://matrix.org" + user_id: "ansible_notification_bot" + password: "{{ matrix_auth_password }}" +''' + +RETURN = ''' +''' + +from ansible.module_utils.basic import AnsibleModule +from matrix_client.client import MatrixClient + +def run_module(): + module_args = dict( + msg_plain=dict(type='str', required=True), + msg_html=dict(type='str', required=True), + room_id=dict(type='str', required=True), + hs_url=dict(type='str', required=True), + token=dict(type='str', required=False), + user_id=dict(type='str', required=False), + password=dict(type='str', required=False), + ) + + result = dict( + changed=False, + message='' + ) + + module = AnsibleModule( + argument_spec=module_args, + supports_check_mode=True + ) + + if module.check_mode: + return result + + client = MatrixClient(module.params['hs_url']) + if module.params['password'] is not None: + if module.params['user_id'] is None: + module.fail_json(msg='If you specify a password, you also need to specify a user_id.', **result) + else: + client.login(module.params['user_id'], module.params['password'], sync=False) + elif module.params['token'] is not None: + client.api.token = module.params['token'] + else: + module.fail_json(msg='You need to either specify a token, or a user_id and password.', **result) + + room = client.join_room(module.params['room_id']) + room.send_html(module.params['msg_html'], module.params['msg_plain']) + + module.exit_json(**result) + +def main(): + run_module() + +if __name__ == '__main__': + main() From b04fbff9f7f620d511950e66d070179693342a47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Wed, 19 Sep 2018 19:29:41 +0200 Subject: [PATCH 02/10] try to make ansibot happy --- lib/ansible/modules/notification/matrix.py | 28 +++++++++++++++++----- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index 91f815eacf65f7..26362102ab85a7 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -1,4 +1,8 @@ #!/usr/bin/python +# coding: utf-8s + +# (c) 2018, Jan Christian Grünhage +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) ANSIBLE_METADATA = { 'metadata_version': '1.1', @@ -12,7 +16,7 @@ short_description: This module can send notifications to matrix rooms -version_added: "2.7" +version_added: "2.8" description: - "This module can send html formatted notifications to matrix rooms" @@ -43,7 +47,7 @@ password: description: - The password to log in with - + author: - Jan Christian Grünhage (@jcgruenhage) @@ -57,7 +61,7 @@ room_id: "!12345678:server.tld" hs_url: "https://matrix.org" token: "{{ matrix_auth_token }}" - + - name: Send matrix notification with user_id and password matrix: msg_plain: "**hello world**" @@ -65,14 +69,21 @@ room_id: "!12345678:server.tld" hs_url: "https://matrix.org" user_id: "ansible_notification_bot" - password: "{{ matrix_auth_password }}" + password: "{{ matrix_auth_password }}" ''' RETURN = ''' ''' from ansible.module_utils.basic import AnsibleModule -from matrix_client.client import MatrixClient + +try: + from matrix_client.client import MatrixClient +except ImportError: + matrix_found = False +else: + matrix_found = True + def run_module(): module_args = dict( @@ -95,6 +106,9 @@ def run_module(): supports_check_mode=True ) + if not matrix_found: + module.fail_json(msg="Python 'matrix-client' module is required. Install via: $ pip install matrix-client") + if module.check_mode: return result @@ -111,11 +125,13 @@ def run_module(): room = client.join_room(module.params['room_id']) room.send_html(module.params['msg_html'], module.params['msg_plain']) - + module.exit_json(**result) + def main(): run_module() + if __name__ == '__main__': main() From a6ce0e1ae9777c202f3141c4d173c9c338855750 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Sat, 29 Sep 2018 13:54:57 +0200 Subject: [PATCH 03/10] docs --- lib/ansible/modules/notification/matrix.py | 44 ++++++++++++---------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index 26362102ab85a7..7fb61237bb1b0a 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -12,58 +12,55 @@ DOCUMENTATION = ''' --- +author: "Jan Christian Grünhage (@jcgruenhage)" +requirements: [ matrix-client ] module: matrix - -short_description: This module can send notifications to matrix rooms - -version_added: "2.8" - +short_description: Send notifications to matrix description: - - "This module can send html formatted notifications to matrix rooms" - + - This module sends html formatted notifications to matrix rooms. +version_added: "2.8" options: msg_plain: description: - - This is the plain text form of the message to send to matrix, usually markdown + - Plain text form of the message to send to matrix, usually markdown required: true msg_html: description: - - This is the html form of the message to send to matrix + - HTML form of the message to send to matrix required: true room_id: description: - - The id of the room to send the notification to + - ID of the room to send the notification to required: true hs_url: description: - - The URL of the homeserver, where the CS-API is reachable + - URL of the homeserver, where the CS-API is reachable required: true token: description: - - The authentication token for the API call. If provided, user_id and password are not required + - Authentication token for the API call. If provided, user_id and password are not required user_id: description: - The user id of the user password: description: - The password to log in with - - -author: - - Jan Christian Grünhage (@jcgruenhage) +notes: + - Requires matrix-client on the executing host. + - Install it with pip install matrix-client. ''' EXAMPLES = ''' -- name: Send matrix notification with token - matrix: +# Send matrix notification with token +- matrix: msg_plain: "**hello world**" msg_html: "hello world" room_id: "!12345678:server.tld" hs_url: "https://matrix.org" token: "{{ matrix_auth_token }}" -- name: Send matrix notification with user_id and password - matrix: +# Send matrix notification with user_id and password +- matrix: msg_plain: "**hello world**" msg_html: "hello world" room_id: "!12345678:server.tld" @@ -74,6 +71,8 @@ RETURN = ''' ''' +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type from ansible.module_utils.basic import AnsibleModule @@ -112,18 +111,23 @@ def run_module(): if module.check_mode: return result + # create a client object client = MatrixClient(module.params['hs_url']) + # try to log in with a password if module.params['password'] is not None: if module.params['user_id'] is None: module.fail_json(msg='If you specify a password, you also need to specify a user_id.', **result) else: client.login(module.params['user_id'], module.params['password'], sync=False) + # use a token if password login isn't possible elif module.params['token'] is not None: client.api.token = module.params['token'] else: module.fail_json(msg='You need to either specify a token, or a user_id and password.', **result) + # make sure we are in a given room and return a room object for it room = client.join_room(module.params['room_id']) + #send an html formatted messages room.send_html(module.params['msg_html'], module.params['msg_plain']) module.exit_json(**result) From 9842e75cfddc88f2b4e20e82e641891d17a57038 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Sat, 29 Sep 2018 13:57:59 +0200 Subject: [PATCH 04/10] fix typo in encoding --- lib/ansible/modules/notification/matrix.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index 7fb61237bb1b0a..4acf60f38fa000 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -1,5 +1,5 @@ #!/usr/bin/python -# coding: utf-8s +# coding: utf-8 # (c) 2018, Jan Christian Grünhage # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) From 4efb8e4df54209c589b634bb5751dedf062995cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Sat, 29 Sep 2018 18:16:40 +0200 Subject: [PATCH 05/10] is ansibot happy now? --- lib/ansible/modules/notification/matrix.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index 4acf60f38fa000..8dbdfb79a095e3 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -4,6 +4,9 @@ # (c) 2018, Jan Christian Grünhage # 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 + ANSIBLE_METADATA = { 'metadata_version': '1.1', 'status': ['preview'], @@ -45,7 +48,7 @@ password: description: - The password to log in with -notes: +notes: - Requires matrix-client on the executing host. - Install it with pip install matrix-client. ''' @@ -71,9 +74,6 @@ RETURN = ''' ''' -from __future__ import (absolute_import, division, print_function) -__metaclass__ = type - from ansible.module_utils.basic import AnsibleModule try: @@ -127,7 +127,7 @@ def run_module(): # make sure we are in a given room and return a room object for it room = client.join_room(module.params['room_id']) - #send an html formatted messages + # send an html formatted messages room.send_html(module.params['msg_html'], module.params['msg_plain']) module.exit_json(**result) From e94bd8e1ddd0fbfaf2cdaf93ef031670cbc95fe9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Wed, 17 Oct 2018 21:44:29 +0200 Subject: [PATCH 06/10] change matrix python lib requirement description --- lib/ansible/modules/notification/matrix.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index 8dbdfb79a095e3..6d257192c70263 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -49,8 +49,7 @@ description: - The password to log in with notes: - - Requires matrix-client on the executing host. - - Install it with pip install matrix-client. + - Requires matrix-client (python library) on the executing host. ''' EXAMPLES = ''' From 56513cdd53e7cbe28b3746bc96fd07981be87d3e Mon Sep 17 00:00:00 2001 From: John R Barker Date: Tue, 23 Oct 2018 12:09:43 +0100 Subject: [PATCH 07/10] Example formatting & no_log Thanks for this PR. Few minor things that are easier for me to just fix, than explain and get you to fix. * We suggest using `- name:` for examples, as Ansible best practice is to name your tasks * To prevent secrets being leaked out use `no_log` in argspec * use `requirements:` in `DOCUMENTATION` --- lib/ansible/modules/notification/matrix.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index 6d257192c70263..dc82004910eeac 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -48,21 +48,21 @@ password: description: - The password to log in with -notes: - - Requires matrix-client (python library) on the executing host. +requirements: + - matrix-client (Python library) ''' EXAMPLES = ''' -# Send matrix notification with token -- matrix: +- name: Send matrix notification with token + matrix: msg_plain: "**hello world**" msg_html: "hello world" room_id: "!12345678:server.tld" hs_url: "https://matrix.org" token: "{{ matrix_auth_token }}" -# Send matrix notification with user_id and password -- matrix: +- name: Send matrix notification with user_id and password + matrix: msg_plain: "**hello world**" msg_html: "hello world" room_id: "!12345678:server.tld" @@ -89,9 +89,9 @@ def run_module(): msg_html=dict(type='str', required=True), room_id=dict(type='str', required=True), hs_url=dict(type='str', required=True), - token=dict(type='str', required=False), + token=dict(type='str', required=False, no_log=True), user_id=dict(type='str', required=False), - password=dict(type='str', required=False), + password=dict(type='str', required=False, no_log=True), ) result = dict( From b55968efb950991acb6d7b4f825d434a501a4e11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Tue, 23 Oct 2018 13:59:56 +0200 Subject: [PATCH 08/10] Clean up argument requirements --- lib/ansible/modules/notification/matrix.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index dc82004910eeac..f29a05812d1bfa 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -101,6 +101,9 @@ def run_module(): module = AnsibleModule( argument_spec=module_args, + mutually_exclusive=(['password', 'token']), + required_one_of=[['password', 'token']], + required_together=(['user_id', 'password']), supports_check_mode=True ) @@ -112,17 +115,10 @@ def run_module(): # create a client object client = MatrixClient(module.params['hs_url']) - # try to log in with a password - if module.params['password'] is not None: - if module.params['user_id'] is None: - module.fail_json(msg='If you specify a password, you also need to specify a user_id.', **result) - else: - client.login(module.params['user_id'], module.params['password'], sync=False) - # use a token if password login isn't possible - elif module.params['token'] is not None: + if module.params['token'] is not None: client.api.token = module.params['token'] else: - module.fail_json(msg='You need to either specify a token, or a user_id and password.', **result) + client.login(module.params['user_id'], module.params['password'], sync=False) # make sure we are in a given room and return a room object for it room = client.join_room(module.params['room_id']) From 108407aa0cedbc23851f5ef8a78e42575e44da11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Tue, 23 Oct 2018 14:02:44 +0200 Subject: [PATCH 09/10] Remove requirements duplicate --- lib/ansible/modules/notification/matrix.py | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index f29a05812d1bfa..d3be2ba47d8eec 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -16,7 +16,6 @@ DOCUMENTATION = ''' --- author: "Jan Christian Grünhage (@jcgruenhage)" -requirements: [ matrix-client ] module: matrix short_description: Send notifications to matrix description: From 08d07910dda020fe08d7708c095e4a6480c80030 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Tue, 23 Oct 2018 23:44:51 +0200 Subject: [PATCH 10/10] not sure on syntax with these, were adapted from an example elsewhere --- lib/ansible/modules/notification/matrix.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/ansible/modules/notification/matrix.py b/lib/ansible/modules/notification/matrix.py index d3be2ba47d8eec..622dbba290c1a5 100644 --- a/lib/ansible/modules/notification/matrix.py +++ b/lib/ansible/modules/notification/matrix.py @@ -100,9 +100,9 @@ def run_module(): module = AnsibleModule( argument_spec=module_args, - mutually_exclusive=(['password', 'token']), + mutually_exclusive=[['password', 'token']], required_one_of=[['password', 'token']], - required_together=(['user_id', 'password']), + required_together=[['user_id', 'password']], supports_check_mode=True )