efro.error

  1# Released under the MIT License. See LICENSE for details.
  2#
  3"""Common errors and related functionality."""
  4from __future__ import annotations
  5
  6from typing import TYPE_CHECKING
  7import errno
  8
  9if TYPE_CHECKING:
 10    from typing import Any
 11
 12    from efro.terminal import ClrBase
 13
 14
 15class CleanError(Exception):
 16    """An error that can be presented to the user as a simple message.
 17
 18    These errors should be completely self-explanatory, to the point where
 19    a traceback or other context would not be useful.
 20
 21    A CleanError with no message can be used to inform a script to fail
 22    without printing any message.
 23
 24    This should generally be limited to errors that will *always* be
 25    presented to the user (such as those in high level tool code).
 26    Exceptions that may be caught and handled by other code should use
 27    more descriptive exception types.
 28    """
 29
 30    def pretty_print(
 31        self,
 32        flush: bool = True,
 33        prefix: str = 'Error',
 34        file: Any = None,
 35        clr: type[ClrBase] | None = None,
 36    ) -> None:
 37        """Print the error to stdout, using red colored output if available.
 38
 39        If the error has an empty message, prints nothing (not even a newline).
 40        """
 41        from efro.terminal import Clr
 42
 43        if clr is None:
 44            clr = Clr
 45
 46        if prefix:
 47            prefix = f'{prefix}: '
 48        errstr = str(self)
 49        if errstr:
 50            print(
 51                f'{clr.SRED}{prefix}{errstr}{clr.RST}', flush=flush, file=file
 52            )
 53
 54
 55class CommunicationError(Exception):
 56    """A communication related error has occurred.
 57
 58    This covers anything network-related going wrong in the sending
 59    of data or receiving of a response. Basically anything that is out
 60    of our control should get lumped in here. This error does not imply
 61    that data was not received on the other end; only that a full
 62    acknowledgement round trip was not completed.
 63
 64    These errors should be gracefully handled whenever possible, as
 65    occasional network issues are unavoidable.
 66    """
 67
 68
 69class RemoteError(Exception):
 70    """An error occurred on the other end of some connection.
 71
 72    This occurs when communication succeeds but another type of error
 73    occurs remotely. The error string can consist of a remote stack
 74    trace or a simple message depending on the context.
 75
 76    Communication systems should raise more specific error types locally
 77    when more introspection/control is needed; this is intended somewhat
 78    as a catch-all.
 79    """
 80
 81    def __init__(self, msg: str, peer_desc: str):
 82        super().__init__(msg)
 83        self._peer_desc = peer_desc
 84
 85    def __str__(self) -> str:
 86        s = ''.join(str(arg) for arg in self.args)
 87        # Indent so we can more easily tell what is the remote part when
 88        # this is in the middle of a long exception chain.
 89        padding = '  '
 90        s = ''.join(padding + line for line in s.splitlines(keepends=True))
 91        return f'The following occurred on {self._peer_desc}:\n{s}'
 92
 93
 94class IntegrityError(ValueError):
 95    """Data has been tampered with or corrupted in some form."""
 96
 97
 98class AuthenticationError(Exception):
 99    """Authentication has failed for some operation.
100
101    This can be raised if server-side-verification does not match
102    client-supplied credentials, if an invalid password is supplied
103    for a sign-in attempt, etc.
104    """
105
106
107def is_urllib_communication_error(exc: BaseException, url: str | None) -> bool:
108    """Is the provided exception from urllib a communication-related error?
109
110    Url, if provided can provide extra context for when to treat an error
111    as such an error.
112
113    This should be passed an exception which resulted from opening or
114    reading a urllib Request. It returns True for any errors that could
115    conceivably arise due to unavailable/poor network connections,
116    firewall/connectivity issues, or other issues out of our control.
117    These errors can often be safely ignored or presented to the user
118    as general 'network-unavailable' states.
119    """
120    import urllib.error
121    import http.client
122    import socket
123
124    if isinstance(
125        exc,
126        (
127            urllib.error.URLError,
128            ConnectionError,
129            http.client.IncompleteRead,
130            http.client.BadStatusLine,
131            http.client.RemoteDisconnected,
132            socket.timeout,
133        ),
134    ):
135        # Special case: although an HTTPError is a subclass of URLError,
136        # we don't consider it a communication error. It generally means we
137        # have successfully communicated with the server but what we are asking
138        # for is not there/etc.
139        if isinstance(exc, urllib.error.HTTPError):
140            # Special sub-case: appspot.com hosting seems to give 403 errors
141            # (forbidden) to some countries. I'm assuming for legal reasons?..
142            # Let's consider that a communication error since its out of our
143            # control so we don't fill up logs with it.
144            if exc.code == 403 and url is not None and '.appspot.com' in url:
145                return True
146
147            return False
148
149        return True
150
151    if isinstance(exc, OSError):
152        if exc.errno == 10051:  # Windows unreachable network error.
153            return True
154        if exc.errno in {
155            errno.ETIMEDOUT,
156            errno.EHOSTUNREACH,
157            errno.ENETUNREACH,
158        }:
159            return True
160    return False
161
162
163def is_requests_communication_error(exc: BaseException) -> bool:
164    """Is the provided exception a communication-related error from requests?"""
165    import requests
166
167    # Looks like this maps pretty well onto requests' ConnectionError
168    return isinstance(exc, requests.ConnectionError)
169
170
171def is_udp_communication_error(exc: BaseException) -> bool:
172    """Should this udp-related exception be considered a communication error?
173
174    This should be passed an exception which resulted from creating and
175    using a socket.SOCK_DGRAM type socket. It should return True for any
176    errors that could conceivably arise due to unavailable/poor network
177    conditions, firewall/connectivity issues, etc. These issues can often
178    be safely ignored or presented to the user as general
179    'network-unavailable' states.
180    """
181    if isinstance(exc, ConnectionRefusedError | TimeoutError):
182        return True
183    if isinstance(exc, OSError):
184        if exc.errno == 10051:  # Windows unreachable network error.
185            return True
186        if exc.errno in {
187            errno.EADDRNOTAVAIL,
188            errno.ETIMEDOUT,
189            errno.EHOSTUNREACH,
190            errno.ENETUNREACH,
191            errno.EINVAL,
192            errno.EPERM,
193            errno.EACCES,
194            # Windows 'invalid argument' error.
195            10022,
196            # Windows 'a socket operation was attempted to'
197            #         'an unreachable network' error.
198            10051,
199        }:
200            return True
201    return False
202
203
204def is_asyncio_streams_communication_error(exc: BaseException) -> bool:
205    """Should this streams error be considered a communication error?
206
207    This should be passed an exception which resulted from creating and
208    using asyncio streams. It should return True for any errors that could
209    conceivably arise due to unavailable/poor network connections,
210    firewall/connectivity issues, etc. These issues can often be safely
211    ignored or presented to the user as general 'connection-lost' events.
212    """
213    # pylint: disable=too-many-return-statements
214    import ssl
215
216    if isinstance(
217        exc,
218        (
219            ConnectionError,
220            TimeoutError,
221            EOFError,
222        ),
223    ):
224        return True
225
226    # Also some specific errno ones.
227    if isinstance(exc, OSError):
228        if exc.errno == 10051:  # Windows unreachable network error.
229            return True
230        if exc.errno in {
231            errno.ETIMEDOUT,
232            errno.EHOSTUNREACH,
233            errno.ENETUNREACH,
234        }:
235            return True
236
237    # Am occasionally getting a specific SSL error on shutdown which I
238    # believe is harmless (APPLICATION_DATA_AFTER_CLOSE_NOTIFY).
239    # It sounds like it may soon be ignored by Python (as of March 2022).
240    # Let's still complain, however, if we get any SSL errors besides
241    # this one. https://bugs.python.org/issue39951
242    if isinstance(exc, ssl.SSLError):
243        excstr = str(exc)
244        if 'APPLICATION_DATA_AFTER_CLOSE_NOTIFY' in excstr:
245            return True
246
247        # Also occasionally am getting WRONG_VERSION_NUMBER ssl errors;
248        # Assuming this just means client is attempting to connect from some
249        # outdated browser or whatnot.
250        if 'SSL: WRONG_VERSION_NUMBER' in excstr:
251            return True
252
253        # And seeing this very rarely; assuming its just data corruption?
254        if 'SSL: DECRYPTION_FAILED_OR_BAD_RECORD_MAC' in excstr:
255            return True
256
257    return False