| 1 |
# This code is part of Ansible, but is an independent component. |
| 2 |
# This particular file snippet, and this file snippet only, is BSD licensed. |
| 3 |
# Modules you write using this snippet, which is embedded dynamically by Ansible |
| 4 |
# still belong to the author of the module, and may assign their own license |
| 5 |
# to the complete work. |
| 6 |
# |
| 7 |
# Copyright (c) 2020, Laurent Nicolas <[email protected]> |
| 8 |
# All rights reserved. |
| 9 |
# |
| 10 |
# Redistribution and use in source and binary forms, with or without modification, |
| 11 |
# are permitted provided that the following conditions are met: |
| 12 |
# |
| 13 |
# * Redistributions of source code must retain the above copyright |
| 14 |
# notice, this list of conditions and the following disclaimer. |
| 15 |
# * Redistributions in binary form must reproduce the above copyright notice, |
| 16 |
# this list of conditions and the following disclaimer in the documentation |
| 17 |
# and/or other materials provided with the distribution. |
| 18 |
# |
| 19 |
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
| 20 |
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| 21 |
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
| 22 |
# IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, |
| 23 |
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 24 |
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| 25 |
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 26 |
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE |
| 27 |
# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 28 |
|
| 29 |
""" Support functions for NetApp ansible modules |
| 30 |
|
| 31 |
Provides common processing for responses and errors from REST calls |
| 32 |
""" |
| 33 |
|
| 34 |
from __future__ import (absolute_import, division, print_function) |
| 35 |
__metaclass__ = type |
| 36 |
|
| 37 |
|
| 38 |
def api_error(api, error): |
| 39 |
"""format error message for api error, if error is present""" |
| 40 |
return "calling: %s: got %s." % (api, error) if error is not None else None |
| 41 |
|
| 42 |
|
| 43 |
def no_response_error(api, response): |
| 44 |
"""format error message for empty response""" |
| 45 |
return "calling: %s: no response %s." % (api, repr(response)) |
| 46 |
|
| 47 |
|
| 48 |
def job_error(response, error): |
| 49 |
"""format error message for job error""" |
| 50 |
return "job reported error: %s, received %s." % (error, repr(response)) |
| 51 |
|
| 52 |
|
| 53 |
def unexpected_response_error(api, response, query=None): |
| 54 |
"""format error message for reponse not matching expectations""" |
| 55 |
msg = "calling: %s: unexpected response %s." % (api, repr(response)) |
| 56 |
if query: |
| 57 |
msg += " for query: %s" % repr(query) |
| 58 |
return response, msg |
| 59 |
|
| 60 |
|
| 61 |
def get_num_records(response): |
| 62 |
""" num_records is not always present |
| 63 |
if absent, count the records or assume 1 |
| 64 |
""" |
| 65 |
if 'num_records' in response: |
| 66 |
return response['num_records'] |
| 67 |
return len(response['records']) if 'records' in response else 1 |
| 68 |
|
| 69 |
|
| 70 |
def check_for_0_or_1_records(api, response, error, query=None): |
| 71 |
"""return None if no record was returned by the API |
| 72 |
return record if one record was returned by the API |
| 73 |
return error otherwise (error, no response, more than 1 record) |
| 74 |
""" |
| 75 |
if error: |
| 76 |
return (None, api_error(api, error)) if api else (None, error) |
| 77 |
if not response: |
| 78 |
return None, no_response_error(api, response) |
| 79 |
num_records = get_num_records(response) |
| 80 |
if num_records == 0: |
| 81 |
return None, None # not found |
| 82 |
if num_records != 1: |
| 83 |
return unexpected_response_error(api, response, query) |
| 84 |
if 'records' in response: |
| 85 |
return response['records'][0], None |
| 86 |
return response, None |
| 87 |
|
| 88 |
|
| 89 |
def check_for_0_or_more_records(api, response, error): |
| 90 |
"""return None if no record was returned by the API |
| 91 |
return records if one or more records was returned by the API |
| 92 |
return error otherwise (error, no response) |
| 93 |
""" |
| 94 |
if error: |
| 95 |
return (None, api_error(api, error)) if api else (None, error) |
| 96 |
if not response: |
| 97 |
return None, no_response_error(api, response) |
| 98 |
if get_num_records(response) == 0: |
| 99 |
return None, None # not found |
| 100 |
if 'records' in response: |
| 101 |
return response['records'], None |
| 102 |
error = 'No "records" key in %s' % response |
| 103 |
return (None, api_error(api, error)) if api else (None, error) |
| 104 |
|
| 105 |
|
| 106 |
def check_for_error_and_job_results(api, response, error, rest_api, **kwargs): |
| 107 |
"""report first error if present |
| 108 |
otherwise call wait_on_job and retrieve job response or error |
| 109 |
""" |
| 110 |
format_error = not kwargs.pop('raw_error', False) |
| 111 |
if error: |
| 112 |
if format_error: |
| 113 |
error = api_error(api, error) |
| 114 |
# we expect two types of response |
| 115 |
# a plain response, for synchronous calls |
| 116 |
# or a job response, for asynchronous calls |
| 117 |
# and it's possible to expect both when 'return_timeout' > 0 |
| 118 |
# |
| 119 |
# when using a query instead of UUID, REST return jobs (a list of jobs) rather than a single job |
| 120 |
# only restit can send a query, all other calls are using a UUID. |
| 121 |
elif isinstance(response, dict): |
| 122 |
job = None |
| 123 |
if 'job' in response: |
| 124 |
job = response['job'] |
| 125 |
elif 'jobs' in response: |
| 126 |
if response['num_records'] > 1: |
| 127 |
error = "multiple jobs in progress, can't check status" |
| 128 |
else: |
| 129 |
job = response['jobs'][0] |
| 130 |
if job: |
| 131 |
job_response, error = rest_api.wait_on_job(job, **kwargs) |
| 132 |
if error: |
| 133 |
if format_error: |
| 134 |
error = job_error(response, error) |
| 135 |
else: |
| 136 |
response['job_response'] = job_response |
| 137 |
return response, error |