From be567d20f7998a9d617736c6ec0794d43742d739 Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Thu, 19 Nov 2026 16:03:55 +0100 Subject: [PATCH 1/3] feat(webhooks): return an error code when a webhook test can't connect Since #7550, a webhook test that fails before getting an HTTP response returns the same message whatever went wrong, and the exception isn't logged. Self-hosted users can't tell a TLS trust problem from DNS, a proxy, a firewall or a timeout. Add a `code` to that 400 response: the POSIX error name (`ECONNREFUSED`, `ETIMEDOUT`, `ECONNRESET`, ...) or, for certificate failures, the Node.js-style OpenSSL verification code (`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `CERT_HAS_EXPIRED`, ...). The code is derived from the exception type and errno only, so no hostnames, addresses or ports reach the client. --- api/core/network.py | 93 ++++++++++ api/tests/unit/core/test_network.py | 168 ++++++++++++++++++ api/tests/unit/webhooks/test_unit_webhooks.py | 39 ++++ api/webhooks/serializers.py | 13 +- api/webhooks/views.py | 4 +- openapi.yaml | 5 +- 6 files changed, 319 insertions(+), 3 deletions(-) create mode 100644 api/tests/unit/core/test_network.py diff --git a/api/core/network.py b/api/core/network.py index 40baad2facba..ad473beecaec 100644 --- a/api/core/network.py +++ b/api/core/network.py @@ -1,9 +1,102 @@ +import errno +import http.client import ipaddress import socket +import ssl +from collections.abc import Iterator + +import requests # RFC 6598 carrier-grade NAT; not caught by ipaddress.is_private. _SHARED_ADDRESS_SPACE = ipaddress.ip_network("100.64.0.0/10") +# OpenSSL X509_V_ERR_* verification results, named as Node.js reports them. +_CERT_VERIFY_ERROR_CODES = { + 2: "UNABLE_TO_GET_ISSUER_CERT", + 3: "UNABLE_TO_GET_CRL", + 4: "UNABLE_TO_DECRYPT_CERT_SIGNATURE", + 5: "UNABLE_TO_DECRYPT_CRL_SIGNATURE", + 6: "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY", + 7: "CERT_SIGNATURE_FAILURE", + 8: "CRL_SIGNATURE_FAILURE", + 9: "CERT_NOT_YET_VALID", + 10: "CERT_HAS_EXPIRED", + 11: "CRL_NOT_YET_VALID", + 12: "CRL_HAS_EXPIRED", + 13: "ERROR_IN_CERT_NOT_BEFORE_FIELD", + 14: "ERROR_IN_CERT_NOT_AFTER_FIELD", + 15: "ERROR_IN_CRL_LAST_UPDATE_FIELD", + 16: "ERROR_IN_CRL_NEXT_UPDATE_FIELD", + 18: "DEPTH_ZERO_SELF_SIGNED_CERT", + 19: "SELF_SIGNED_CERT_IN_CHAIN", + 20: "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", + 21: "UNABLE_TO_VERIFY_LEAF_SIGNATURE", + 22: "CERT_CHAIN_TOO_LONG", + 23: "CERT_REVOKED", + 24: "INVALID_CA", + 25: "PATH_LENGTH_EXCEEDED", + 26: "INVALID_PURPOSE", + 27: "CERT_UNTRUSTED", + 28: "CERT_REJECTED", + 62: "ERR_TLS_CERT_ALTNAME_INVALID", # X509_V_ERR_HOSTNAME_MISMATCH +} + + +def get_request_error_code(error: requests.RequestException) -> str: + """Return a POSIX error name (e.g. `ECONNREFUSED`), or a Node.js-style + TLS error code (e.g. `CERT_HAS_EXPIRED`), for a request that failed + without an HTTP response. + + Unlike the exception text, the code carries no hostnames, addresses or + ports, so it is safe to show to the user who made the request.""" + if isinstance(error, requests.exceptions.ConnectTimeout): + return "ETIMEDOUT" + if isinstance(error, requests.exceptions.ReadTimeout): + return "ESOCKETTIMEDOUT" + for exc in _iter_exception_chain(error): + if code := _get_exception_error_code(exc): + return code + return "UNKNOWN" + + +def _get_exception_error_code(exc: BaseException) -> str | None: + # SSL errors subclass OSError, with an OpenSSL-specific errno. + if isinstance(exc, ssl.SSLCertVerificationError): + return _CERT_VERIFY_ERROR_CODES.get(exc.verify_code, "EPROTO") + if isinstance(exc, ssl.SSLError): + return "EPROTO" + # gaierror carries an EAI_* errno, not a POSIX one. + if isinstance(exc, socket.gaierror): + return "EAI_AGAIN" if exc.errno == socket.EAI_AGAIN else "ENOTFOUND" + if isinstance(exc, OSError) and exc.errno is not None: + if name := errno.errorcode.get(exc.errno): + return name + # e.g. `RemoteDisconnected`: the peer closed without responding. + if isinstance(exc, ConnectionResetError): + return "ECONNRESET" + # The peer responded with something other than HTTP. + if isinstance(exc, http.client.HTTPException): + return "EPROTO" + return None + + +def _iter_exception_chain(error: BaseException) -> Iterator[BaseException]: + # requests and urllib3 wrap the underlying error in `reason` and + # `original_error` as well as in the standard `__cause__`/`__context__`. + seen: set[int] = set() + pending: list[BaseException] = [error] + while pending: + exc = pending.pop(0) + if id(exc) in seen: + continue + seen.add(id(exc)) + yield exc + for attr in ("reason", "original_error", "__cause__", "__context__"): + linked = getattr(exc, attr, None) + if isinstance(linked, BaseException): + pending.append(linked) + pending.extend(arg for arg in exc.args if isinstance(arg, BaseException)) + def is_internal_address( hostname: str, diff --git a/api/tests/unit/core/test_network.py b/api/tests/unit/core/test_network.py new file mode 100644 index 000000000000..e1f8c31f1f81 --- /dev/null +++ b/api/tests/unit/core/test_network.py @@ -0,0 +1,168 @@ +import errno +import http.client +import socket +import ssl + +import pytest +import requests +from urllib3.exceptions import ( + MaxRetryError, + NameResolutionError, + NewConnectionError, + ProtocolError, +) +from urllib3.exceptions import ProxyError as Urllib3ProxyError +from urllib3.exceptions import SSLError as Urllib3SSLError + +from core.network import get_request_error_code + + +def _caused_by(error: BaseException, cause: BaseException) -> BaseException: + error.__cause__ = cause + return error + + +def _max_retries(reason: Exception) -> MaxRetryError: + # How requests' HTTPAdapter receives connection failures from urllib3. + return MaxRetryError(None, "/", reason=reason) # type: ignore[arg-type] + + +def _cert_verify_error(verify_code: int) -> ssl.SSLCertVerificationError: + error = ssl.SSLCertVerificationError(1, "certificate verify failed") + error.verify_code = verify_code + return error + + +def _new_connection_error(cause: OSError) -> NewConnectionError: + return _caused_by( # type: ignore[return-value] + NewConnectionError(None, "Failed to establish a new connection"), # type: ignore[arg-type] + cause, + ) + + +@pytest.mark.parametrize( + "error, expected_code", + [ + ( + requests.exceptions.ConnectionError( + _max_retries( + _new_connection_error( + ConnectionRefusedError(errno.ECONNREFUSED, "refused") + ) + ) + ), + "ECONNREFUSED", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _new_connection_error(OSError(errno.EHOSTUNREACH, "no route")) + ) + ), + "EHOSTUNREACH", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NameResolutionError("example.com", None, None), # type: ignore[arg-type] + socket.gaierror(socket.EAI_NONAME, "Name not known"), + ) + ) + ), + "ENOTFOUND", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NameResolutionError("example.com", None, None), # type: ignore[arg-type] + socket.gaierror(socket.EAI_AGAIN, "Temporary failure"), + ) + ) + ), + "EAI_AGAIN", + ), + ( + requests.exceptions.ConnectionError( + ProtocolError( + "Connection aborted.", + ConnectionResetError(errno.ECONNRESET, "reset by peer"), + ) + ), + "ECONNRESET", + ), + ( + requests.exceptions.ConnectionError( + ProtocolError( + "Connection aborted.", + http.client.RemoteDisconnected("closed without response"), + ) + ), + "ECONNRESET", + ), + ( + requests.exceptions.ConnectionError( + ProtocolError("Connection aborted.", http.client.BadStatusLine("SSH")) + ), + "EPROTO", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(20))) + ), + "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(10))) + ), + "CERT_HAS_EXPIRED", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(62))) + ), + "ERR_TLS_CERT_ALTNAME_INVALID", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(-1))) + ), + "EPROTO", + ), + ( + requests.exceptions.SSLError( + _max_retries( + Urllib3SSLError(ssl.SSLError(1, "[SSL] wrong version number")) + ) + ), + "EPROTO", + ), + ( + requests.exceptions.ProxyError( + _max_retries( + Urllib3ProxyError( + "Unable to connect to proxy", + _new_connection_error( + ConnectionRefusedError(errno.ECONNREFUSED, "refused") + ), + ) + ) + ), + "ECONNREFUSED", + ), + (requests.exceptions.ConnectTimeout("timed out"), "ETIMEDOUT"), + (requests.exceptions.ReadTimeout("timed out"), "ESOCKETTIMEDOUT"), + (requests.exceptions.RequestException("unexpected"), "UNKNOWN"), + ], +) +def test_get_request_error_code__request_failed__returns_expected_code( + error: requests.RequestException, + expected_code: str, +) -> None: + # Given / When + code = get_request_error_code(error) + + # Then + assert code == expected_code diff --git a/api/tests/unit/webhooks/test_unit_webhooks.py b/api/tests/unit/webhooks/test_unit_webhooks.py index 411e629ea4fe..edbc1557e6cc 100644 --- a/api/tests/unit/webhooks/test_unit_webhooks.py +++ b/api/tests/unit/webhooks/test_unit_webhooks.py @@ -1,3 +1,4 @@ +import errno import hashlib import hmac import json @@ -605,6 +606,44 @@ def test_send_test_webhook__request_exception__returns_error_response( assert response.json() == { "detail": "Could not connect to webhook URL", "body": "Please check the URL, and ensure it is valid and accessible from the server.", + "code": "UNKNOWN", + } + + +def test_send_test_webhook__connection_refused__returns_error_code_without_details( + mocker: MockerFixture, + admin_client: APIClient, + organisation: Organisation, +) -> None: + # Given + mocker.patch( + "core.network.socket.getaddrinfo", + return_value=[(socket.AF_INET, None, None, None, ("93.184.216.34", 0))], + ) + refused = ConnectionRefusedError( + errno.ECONNREFUSED, "Connection refused by 10.1.2.3:7000" + ) + error = ConnectionError("HTTPSConnectionPool(host='example.com', port=7000)") + error.__cause__ = refused + mocker.patch("webhooks.webhooks.requests.post", side_effect=error) + + url = reverse("api-v1:webhooks:webhooks-test") + data = { + "webhook_url": "https://example.com:7000/hook", + "scope": {"type": "organisation", "id": organisation.id}, + } + + # When + response = admin_client.post( + url, data=json.dumps(data), content_type="application/json" + ) + + # Then + assert response.status_code == status.HTTP_400_BAD_REQUEST + assert response.json() == { + "detail": "Could not connect to webhook URL", + "body": "Please check the URL, and ensure it is valid and accessible from the server.", + "code": "ECONNREFUSED", } diff --git a/api/webhooks/serializers.py b/api/webhooks/serializers.py index ef8ee518a837..1e2c824dff44 100644 --- a/api/webhooks/serializers.py +++ b/api/webhooks/serializers.py @@ -29,5 +29,16 @@ class TestWebhookSuccessResponseSerializer(serializers.Serializer[None]): class TestWebhookErrorResponseSerializer(serializers.Serializer[None]): detail = serializers.CharField() - status = serializers.IntegerField() + status = serializers.IntegerField( + required=False, + help_text="HTTP status returned by the webhook, if it responded.", + ) body = serializers.CharField(required=False, allow_blank=True, allow_null=True) + code = serializers.CharField( + required=False, + help_text=( + "Set when the webhook could not be reached: a POSIX error name" + " (e.g. `ECONNREFUSED`, `ETIMEDOUT`) or a Node.js-style TLS" + " error code (e.g. `CERT_HAS_EXPIRED`)." + ), + ) diff --git a/api/webhooks/views.py b/api/webhooks/views.py index bf467c467e90..8c1b8d053023 100644 --- a/api/webhooks/views.py +++ b/api/webhooks/views.py @@ -6,6 +6,7 @@ from rest_framework.request import Request from rest_framework.response import Response +from core.network import get_request_error_code from webhooks.webhooks import WebhookType from .permissions import TriggerSampleWebhookPermission @@ -63,11 +64,12 @@ def test(self, request: Request) -> Response: }, status=status.HTTP_200_OK, ) - except requests.exceptions.RequestException: + except requests.exceptions.RequestException as error: return Response( { "detail": "Could not connect to webhook URL", "body": "Please check the URL, and ensure it is valid and accessible from the server.", + "code": get_request_error_code(error), }, status=status.HTTP_400_BAD_REQUEST, ) diff --git a/openapi.yaml b/openapi.yaml index b2ca9cd8e1e5..61fb3494be4c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -29065,14 +29065,17 @@ components: detail: type: string status: + description: 'HTTP status returned by the webhook, if it responded.' type: integer body: type: - string - 'null' + code: + description: 'Set when the webhook could not be reached: a POSIX error name (e.g. `ECONNREFUSED`, `ETIMEDOUT`) or a Node.js-style TLS error code (e.g. `CERT_HAS_EXPIRED`).' + type: string required: - detail - - status TestWebhookSuccessResponse: type: object properties: From f83549845b6b4f742edf2e7a29a4a91c9f738d56 Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Thu, 19 Nov 2026 16:22:58 +0100 Subject: [PATCH 2/3] docs(webhooks): shorten error code docstring and help text --- api/core/network.py | 8 ++------ api/webhooks/serializers.py | 5 ++--- openapi.yaml | 2 +- 3 files changed, 5 insertions(+), 10 deletions(-) diff --git a/api/core/network.py b/api/core/network.py index ad473beecaec..3dae6a15ddd2 100644 --- a/api/core/network.py +++ b/api/core/network.py @@ -43,12 +43,8 @@ def get_request_error_code(error: requests.RequestException) -> str: - """Return a POSIX error name (e.g. `ECONNREFUSED`), or a Node.js-style - TLS error code (e.g. `CERT_HAS_EXPIRED`), for a request that failed - without an HTTP response. - - Unlike the exception text, the code carries no hostnames, addresses or - ports, so it is safe to show to the user who made the request.""" + """Return a POSIX error name, or a Node.js-style TLS error code, + for a request that failed without an HTTP response.""" if isinstance(error, requests.exceptions.ConnectTimeout): return "ETIMEDOUT" if isinstance(error, requests.exceptions.ReadTimeout): diff --git a/api/webhooks/serializers.py b/api/webhooks/serializers.py index 1e2c824dff44..747254393fad 100644 --- a/api/webhooks/serializers.py +++ b/api/webhooks/serializers.py @@ -37,8 +37,7 @@ class TestWebhookErrorResponseSerializer(serializers.Serializer[None]): code = serializers.CharField( required=False, help_text=( - "Set when the webhook could not be reached: a POSIX error name" - " (e.g. `ECONNREFUSED`, `ETIMEDOUT`) or a Node.js-style TLS" - " error code (e.g. `CERT_HAS_EXPIRED`)." + "A POSIX error name, or a TLS error code, when " + "the webhook could not be reached." ), ) diff --git a/openapi.yaml b/openapi.yaml index 61fb3494be4c..ab3af8f81a3d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -29072,7 +29072,7 @@ components: - string - 'null' code: - description: 'Set when the webhook could not be reached: a POSIX error name (e.g. `ECONNREFUSED`, `ETIMEDOUT`) or a Node.js-style TLS error code (e.g. `CERT_HAS_EXPIRED`).' + description: 'A POSIX error name, or a TLS error code, when the webhook could not be reached.' type: string required: - detail From 1417a19a8b2631a6f253e29662647d0874e6ef3d Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Thu, 19 Nov 2026 16:42:33 +0100 Subject: [PATCH 3/3] fix(webhooks): use standard error names for webhook test error codes - Name certificate failures with OpenSSL's X509_V_ERR_* constants, numbered as in OpenSSL 3+, where 24 is NO_ISSUER_PUBLIC_KEY and INVALID_CA is 79. - Name DNS failures with their getaddrinfo EAI_* code, instead of reporting every resolver error as ENOTFOUND. - Report read timeouts, and timeouts connecting to a proxy, as ETIMEDOUT. - Omit `code` when the cause isn't recognised, rather than returning UNKNOWN. - Build real urllib3 objects in tests, removing the type ignores. --- api/core/network.py | 91 +++++++++------- api/tests/unit/core/test_network.py | 103 ++++++++++++++---- api/tests/unit/webhooks/test_unit_webhooks.py | 1 - api/webhooks/serializers.py | 4 +- api/webhooks/views.py | 15 ++- openapi.yaml | 2 +- 6 files changed, 141 insertions(+), 75 deletions(-) diff --git a/api/core/network.py b/api/core/network.py index 3dae6a15ddd2..5d6f081403a5 100644 --- a/api/core/network.py +++ b/api/core/network.py @@ -10,63 +10,74 @@ # RFC 6598 carrier-grade NAT; not caught by ipaddress.is_private. _SHARED_ADDRESS_SPACE = ipaddress.ip_network("100.64.0.0/10") -# OpenSSL X509_V_ERR_* verification results, named as Node.js reports them. -_CERT_VERIFY_ERROR_CODES = { - 2: "UNABLE_TO_GET_ISSUER_CERT", - 3: "UNABLE_TO_GET_CRL", - 4: "UNABLE_TO_DECRYPT_CERT_SIGNATURE", - 5: "UNABLE_TO_DECRYPT_CRL_SIGNATURE", - 6: "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY", - 7: "CERT_SIGNATURE_FAILURE", - 8: "CRL_SIGNATURE_FAILURE", - 9: "CERT_NOT_YET_VALID", - 10: "CERT_HAS_EXPIRED", - 11: "CRL_NOT_YET_VALID", - 12: "CRL_HAS_EXPIRED", - 13: "ERROR_IN_CERT_NOT_BEFORE_FIELD", - 14: "ERROR_IN_CERT_NOT_AFTER_FIELD", - 15: "ERROR_IN_CRL_LAST_UPDATE_FIELD", - 16: "ERROR_IN_CRL_NEXT_UPDATE_FIELD", - 18: "DEPTH_ZERO_SELF_SIGNED_CERT", - 19: "SELF_SIGNED_CERT_IN_CHAIN", - 20: "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", - 21: "UNABLE_TO_VERIFY_LEAF_SIGNATURE", - 22: "CERT_CHAIN_TOO_LONG", - 23: "CERT_REVOKED", - 24: "INVALID_CA", - 25: "PATH_LENGTH_EXCEEDED", - 26: "INVALID_PURPOSE", - 27: "CERT_UNTRUSTED", - 28: "CERT_REJECTED", - 62: "ERR_TLS_CERT_ALTNAME_INVALID", # X509_V_ERR_HOSTNAME_MISMATCH +# OpenSSL 3+ certificate verification results, from `include/openssl/x509_vfy.h`. +# Python exposes the numeric `verify_code`, but not the constant names. +_CERT_VERIFY_ERROR_NAMES = { + 2: "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT", + 3: "X509_V_ERR_UNABLE_TO_GET_CRL", + 4: "X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE", + 5: "X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE", + 6: "X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY", + 7: "X509_V_ERR_CERT_SIGNATURE_FAILURE", + 8: "X509_V_ERR_CRL_SIGNATURE_FAILURE", + 9: "X509_V_ERR_CERT_NOT_YET_VALID", + 10: "X509_V_ERR_CERT_HAS_EXPIRED", + 11: "X509_V_ERR_CRL_NOT_YET_VALID", + 12: "X509_V_ERR_CRL_HAS_EXPIRED", + 13: "X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD", + 14: "X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD", + 15: "X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD", + 16: "X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD", + 18: "X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT", + 19: "X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN", + 20: "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY", + 21: "X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE", + 22: "X509_V_ERR_CERT_CHAIN_TOO_LONG", + 23: "X509_V_ERR_CERT_REVOKED", + 24: "X509_V_ERR_NO_ISSUER_PUBLIC_KEY", + 25: "X509_V_ERR_PATH_LENGTH_EXCEEDED", + 26: "X509_V_ERR_INVALID_PURPOSE", + 27: "X509_V_ERR_CERT_UNTRUSTED", + 28: "X509_V_ERR_CERT_REJECTED", + 62: "X509_V_ERR_HOSTNAME_MISMATCH", + 64: "X509_V_ERR_IP_ADDRESS_MISMATCH", + 66: "X509_V_ERR_EE_KEY_TOO_SMALL", + 67: "X509_V_ERR_CA_KEY_TOO_SMALL", + 68: "X509_V_ERR_CA_MD_TOO_WEAK", + 79: "X509_V_ERR_INVALID_CA", +} + +# getaddrinfo() returns EAI_* codes, which don't overlap with errno. +_GETADDRINFO_ERROR_NAMES = { + getattr(socket, name): name for name in dir(socket) if name.startswith("EAI_") } -def get_request_error_code(error: requests.RequestException) -> str: - """Return a POSIX error name, or a Node.js-style TLS error code, - for a request that failed without an HTTP response.""" - if isinstance(error, requests.exceptions.ConnectTimeout): +def get_request_error_code(error: requests.RequestException) -> str | None: + """Return the POSIX error name, or the OpenSSL certificate verification + error name, for a request that failed without an HTTP response.""" + if isinstance(error, requests.exceptions.Timeout): return "ETIMEDOUT" - if isinstance(error, requests.exceptions.ReadTimeout): - return "ESOCKETTIMEDOUT" for exc in _iter_exception_chain(error): if code := _get_exception_error_code(exc): return code - return "UNKNOWN" + return None def _get_exception_error_code(exc: BaseException) -> str | None: # SSL errors subclass OSError, with an OpenSSL-specific errno. if isinstance(exc, ssl.SSLCertVerificationError): - return _CERT_VERIFY_ERROR_CODES.get(exc.verify_code, "EPROTO") + return _CERT_VERIFY_ERROR_NAMES.get(exc.verify_code, "EPROTO") if isinstance(exc, ssl.SSLError): return "EPROTO" - # gaierror carries an EAI_* errno, not a POSIX one. - if isinstance(exc, socket.gaierror): - return "EAI_AGAIN" if exc.errno == socket.EAI_AGAIN else "ENOTFOUND" + if isinstance(exc, socket.gaierror) and exc.errno is not None: + return _GETADDRINFO_ERROR_NAMES.get(exc.errno) if isinstance(exc, OSError) and exc.errno is not None: if name := errno.errorcode.get(exc.errno): return name + # A socket timeout, e.g. connecting to a proxy, without an errno. + if isinstance(exc, TimeoutError): + return "ETIMEDOUT" # e.g. `RemoteDisconnected`: the peer closed without responding. if isinstance(exc, ConnectionResetError): return "ECONNRESET" diff --git a/api/tests/unit/core/test_network.py b/api/tests/unit/core/test_network.py index e1f8c31f1f81..d2be751f9e98 100644 --- a/api/tests/unit/core/test_network.py +++ b/api/tests/unit/core/test_network.py @@ -2,10 +2,14 @@ import http.client import socket import ssl +from typing import TypeVar import pytest import requests +from urllib3 import HTTPSConnectionPool +from urllib3.connection import HTTPSConnection from urllib3.exceptions import ( + ConnectTimeoutError, MaxRetryError, NameResolutionError, NewConnectionError, @@ -16,15 +20,21 @@ from core.network import get_request_error_code +_E = TypeVar("_E", bound=BaseException) -def _caused_by(error: BaseException, cause: BaseException) -> BaseException: +# Constructing these doesn't open a connection. +_POOL = HTTPSConnectionPool("example.com") +_CONN = HTTPSConnection("example.com") + + +def _caused_by(error: _E, cause: BaseException) -> _E: error.__cause__ = cause return error def _max_retries(reason: Exception) -> MaxRetryError: # How requests' HTTPAdapter receives connection failures from urllib3. - return MaxRetryError(None, "/", reason=reason) # type: ignore[arg-type] + return MaxRetryError(_POOL, "/", reason=reason) def _cert_verify_error(verify_code: int) -> ssl.SSLCertVerificationError: @@ -33,21 +43,15 @@ def _cert_verify_error(verify_code: int) -> ssl.SSLCertVerificationError: return error -def _new_connection_error(cause: OSError) -> NewConnectionError: - return _caused_by( # type: ignore[return-value] - NewConnectionError(None, "Failed to establish a new connection"), # type: ignore[arg-type] - cause, - ) - - @pytest.mark.parametrize( "error, expected_code", [ ( requests.exceptions.ConnectionError( _max_retries( - _new_connection_error( - ConnectionRefusedError(errno.ECONNREFUSED, "refused") + _caused_by( + NewConnectionError(_CONN, "Failed to establish a connection"), + ConnectionRefusedError(errno.ECONNREFUSED, "refused"), ) ) ), @@ -56,7 +60,10 @@ def _new_connection_error(cause: OSError) -> NewConnectionError: ( requests.exceptions.ConnectionError( _max_retries( - _new_connection_error(OSError(errno.EHOSTUNREACH, "no route")) + _caused_by( + NewConnectionError(_CONN, "Failed to establish a connection"), + OSError(errno.EHOSTUNREACH, "no route to host"), + ) ) ), "EHOSTUNREACH", @@ -65,24 +72,47 @@ def _new_connection_error(cause: OSError) -> NewConnectionError: requests.exceptions.ConnectionError( _max_retries( _caused_by( - NameResolutionError("example.com", None, None), # type: ignore[arg-type] + NameResolutionError( + "example.com", + _CONN, + socket.gaierror(socket.EAI_NONAME, "Name not known"), + ), socket.gaierror(socket.EAI_NONAME, "Name not known"), ) ) ), - "ENOTFOUND", + "EAI_NONAME", ), ( requests.exceptions.ConnectionError( _max_retries( _caused_by( - NameResolutionError("example.com", None, None), # type: ignore[arg-type] + NameResolutionError( + "example.com", + _CONN, + socket.gaierror(socket.EAI_AGAIN, "Temporary failure"), + ), socket.gaierror(socket.EAI_AGAIN, "Temporary failure"), ) ) ), "EAI_AGAIN", ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NameResolutionError( + "example.com", + _CONN, + socket.gaierror(socket.EAI_FAIL, "Non-recoverable"), + ), + socket.gaierror(socket.EAI_FAIL, "Non-recoverable"), + ) + ) + ), + "EAI_FAIL", + ), ( requests.exceptions.ConnectionError( ProtocolError( @@ -111,19 +141,31 @@ def _new_connection_error(cause: OSError) -> NewConnectionError: requests.exceptions.SSLError( _max_retries(Urllib3SSLError(_cert_verify_error(20))) ), - "UNABLE_TO_GET_ISSUER_CERT_LOCALLY", + "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY", ), ( requests.exceptions.SSLError( _max_retries(Urllib3SSLError(_cert_verify_error(10))) ), - "CERT_HAS_EXPIRED", + "X509_V_ERR_CERT_HAS_EXPIRED", ), ( requests.exceptions.SSLError( _max_retries(Urllib3SSLError(_cert_verify_error(62))) ), - "ERR_TLS_CERT_ALTNAME_INVALID", + "X509_V_ERR_HOSTNAME_MISMATCH", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(24))) + ), + "X509_V_ERR_NO_ISSUER_PUBLIC_KEY", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(79))) + ), + "X509_V_ERR_INVALID_CA", ), ( requests.exceptions.SSLError( @@ -144,22 +186,37 @@ def _new_connection_error(cause: OSError) -> NewConnectionError: _max_retries( Urllib3ProxyError( "Unable to connect to proxy", - _new_connection_error( - ConnectionRefusedError(errno.ECONNREFUSED, "refused") + _caused_by( + NewConnectionError(_CONN, "Failed to establish"), + ConnectionRefusedError(errno.ECONNREFUSED, "refused"), ), ) ) ), "ECONNREFUSED", ), + ( + requests.exceptions.ProxyError( + _max_retries( + Urllib3ProxyError( + "Unable to connect to proxy", + _caused_by( + ConnectTimeoutError(_CONN, "Connection timed out"), + TimeoutError("timed out"), + ), + ) + ) + ), + "ETIMEDOUT", + ), (requests.exceptions.ConnectTimeout("timed out"), "ETIMEDOUT"), - (requests.exceptions.ReadTimeout("timed out"), "ESOCKETTIMEDOUT"), - (requests.exceptions.RequestException("unexpected"), "UNKNOWN"), + (requests.exceptions.ReadTimeout("timed out"), "ETIMEDOUT"), + (requests.exceptions.RequestException("unexpected"), None), ], ) def test_get_request_error_code__request_failed__returns_expected_code( error: requests.RequestException, - expected_code: str, + expected_code: str | None, ) -> None: # Given / When code = get_request_error_code(error) diff --git a/api/tests/unit/webhooks/test_unit_webhooks.py b/api/tests/unit/webhooks/test_unit_webhooks.py index edbc1557e6cc..96b5c8dd2b53 100644 --- a/api/tests/unit/webhooks/test_unit_webhooks.py +++ b/api/tests/unit/webhooks/test_unit_webhooks.py @@ -606,7 +606,6 @@ def test_send_test_webhook__request_exception__returns_error_response( assert response.json() == { "detail": "Could not connect to webhook URL", "body": "Please check the URL, and ensure it is valid and accessible from the server.", - "code": "UNKNOWN", } diff --git a/api/webhooks/serializers.py b/api/webhooks/serializers.py index 747254393fad..bf04c44c5cf0 100644 --- a/api/webhooks/serializers.py +++ b/api/webhooks/serializers.py @@ -37,7 +37,7 @@ class TestWebhookErrorResponseSerializer(serializers.Serializer[None]): code = serializers.CharField( required=False, help_text=( - "A POSIX error name, or a TLS error code, when " - "the webhook could not be reached." + "Why the webhook could not be reached, if known: a POSIX error " + "name, or an OpenSSL certificate verification error name." ), ) diff --git a/api/webhooks/views.py b/api/webhooks/views.py index 8c1b8d053023..b1ac3818b6e1 100644 --- a/api/webhooks/views.py +++ b/api/webhooks/views.py @@ -65,11 +65,10 @@ def test(self, request: Request) -> Response: status=status.HTTP_200_OK, ) except requests.exceptions.RequestException as error: - return Response( - { - "detail": "Could not connect to webhook URL", - "body": "Please check the URL, and ensure it is valid and accessible from the server.", - "code": get_request_error_code(error), - }, - status=status.HTTP_400_BAD_REQUEST, - ) + error_data = { + "detail": "Could not connect to webhook URL", + "body": "Please check the URL, and ensure it is valid and accessible from the server.", + } + if code := get_request_error_code(error): + error_data["code"] = code + return Response(error_data, status=status.HTTP_400_BAD_REQUEST) diff --git a/openapi.yaml b/openapi.yaml index ab3af8f81a3d..9b7ff0a0d913 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -29072,7 +29072,7 @@ components: - string - 'null' code: - description: 'A POSIX error name, or a TLS error code, when the webhook could not be reached.' + description: 'Why the webhook could not be reached, if known: a POSIX error name, or an OpenSSL certificate verification error name.' type: string required: - detail