From c4e969561e3751c21cab2ae890ad6e14c9abbe40 Mon Sep 17 00:00:00 2001 From: James Knight Date: Thu, 27 Jun 2024 01:16:15 -0400 Subject: [PATCH 1/2] add support for logging request/response body data Extend the logging capabilities for publish events to support logging the contents of body data for requests and responses. This adds the `headers_and_data` option to hint to have both headers and their content (if printable content). Signed-off-by: James Knight --- sphinxcontrib/confluencebuilder/debug.py | 6 +++++- sphinxcontrib/confluencebuilder/rest.py | 20 ++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/sphinxcontrib/confluencebuilder/debug.py b/sphinxcontrib/confluencebuilder/debug.py index 1c0a1874..30ce07fa 100644 --- a/sphinxcontrib/confluencebuilder/debug.py +++ b/sphinxcontrib/confluencebuilder/debug.py @@ -18,16 +18,20 @@ class PublishDebug(Flag): # do not perform any logging none = auto() + # log raw requests/responses in stdout with body data + data = auto() # logs warnings when confluence reports a deprecated api call deprecated = auto() # log raw requests/responses in stdout with header data (redacted auth) headers = auto() + # log both header and body data + headers_and_data = headers | data # log raw requests/responses in stdout with header data (no redactions) _headers_raw = auto() headers_raw = headers | _headers_raw # log urllib3-supported debug messages urllib3 = auto() # enable all logging - all = headers | urllib3 + all = data | headers | urllib3 # enable all developer logging developer = deprecated | all diff --git a/sphinxcontrib/confluencebuilder/rest.py b/sphinxcontrib/confluencebuilder/rest.py index 3199e35b..6c4688ce 100644 --- a/sphinxcontrib/confluencebuilder/rest.py +++ b/sphinxcontrib/confluencebuilder/rest.py @@ -403,6 +403,7 @@ def _format_error(self, rsp, path): def _process_request(self, method, path, *args, **kwargs): publish_debug_opts = self.config.confluence_publish_debug dump = PublishDebug.headers in publish_debug_opts + dump_body = PublishDebug.headers_and_data in publish_debug_opts rest_url = f'{self.url}{path}' base_req = requests.Request(method, rest_url, *args, **kwargs) @@ -431,6 +432,15 @@ def _process_request(self, method, path, *args, **kwargs): print('\n'.join(f'{k}: {v}' for k, v in filtered_headers.items())) print('', flush=True) + if dump_body and req.body: + print('(debug) Request data]') + try: + json_data = json.dumps(json.loads(req.body), indent=2) + print(json_data) + except TypeError: + print('(non-json)') + print('', flush=True) + # perform the rest request rsp = self.session.send(req, timeout=self.timeout) @@ -441,6 +451,16 @@ def _process_request(self, method, path, *args, **kwargs): print('\n'.join(f'{k}: {v}' for k, v in rsp.headers.items())) print('', flush=True) + if dump_body and rsp.text: + print('(debug) Response data]') + try: + rsp.encoding = self.CONFLUENCE_DEFAULT_ENCODING + json_data = json.dumps(json.loads(rsp.text), indent=2) + print(json_data) + except ValueError: + print('(non-json)') + print('', flush=True) + # if confluence or a proxy reports a retry-after delay (to pace us), # track it to delay the next request made # (https://datatracker.ietf.org/doc/html/rfc2616.html#section-14.37) From ef5445ceeac3077775d91dd7aaf56617f8be0382 Mon Sep 17 00:00:00 2001 From: James Knight Date: Thu, 27 Jun 2024 01:16:29 -0400 Subject: [PATCH 2/2] doc: document new publish debug new header-data mode Signed-off-by: James Knight --- doc/configuration.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/configuration.rst b/doc/configuration.rst index 91b237c0..804d0e3b 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -1519,6 +1519,10 @@ Advanced publishing configuration Switched from boolean to string for setting new debugging options. + .. versionchanged:: 2.6 + + Introduce the ``headers_and_data`` option. + .. warning:: Enabling certain debugging options may reveal information such as @@ -1537,6 +1541,7 @@ Advanced publishing configuration - ``deprecated``: Log warnings when a deprecated API call is used (*for development purposes*). - ``headers``: Log requests and responses, including their headers. + - ``headers_and_data``: Log header data along with request/response bodies. - ``urllib3``: Enable urllib3 library debugging messages. An example debugging configuration is as follows: