backlash 0.4.0__py3-none-any.whl

backlash/tracing/errors/middleware.py

@@ -0,0 +1,85 @@
+from backlash._compat import string_types, bytes_
+from backlash.tbtools import get_current_traceback
+from backlash.utils import RequestContext
+
+import logging
+log = logging.getLogger('backlash')
+
+
+class TraceErrorsMiddleware(object):
+    def __init__(self, application, reporters, context_injectors):
+        self.app = application
+        self.reporters = reporters
+        self.context_injectors = context_injectors
+
+    def _report_errors(self, environ, recorded_exc_info=None):
+        context = RequestContext({'environ': dict(environ)})
+        for injector in self.context_injectors:
+            context.update(injector(environ))
+
+        traceback = get_current_traceback(skip=2, show_hidden_frames=False, context=context,
+                                          exc_info=recorded_exc_info)
+
+        # This will lead to double logging in case backlash logger is set to DEBUG
+        # but this is actually wanted as some environments, like WebTest, swallow
+        # wsgi.environ making the traceback totally disappear.
+        log.debug(traceback.plaintext)
+        traceback.log(environ['wsgi.errors'])
+
+        for r in self.reporters:
+            try:
+                r.report(traceback)
+            except Exception:
+                error = get_current_traceback(skip=1, show_hidden_frames=False)
+                environ['wsgi.errors'].write('\nError while reporting exception with %s\n' % r)
+                environ['wsgi.errors'].write(error.plaintext)
+
+    def _generate_response(self, environ, start_response):
+        try:
+            start_response('500 INTERNAL SERVER ERROR', [
+                ('Content-Type', 'text/html; charset=utf-8'),
+                # Disable Chrome's XSS protection, the debug
+                # output can cause false-positives.
+                ('X-XSS-Protection', '0'),
+                ])
+        except Exception:
+            # if we end up here there has been output but an error
+            # occurred.  in that situation we can do nothing fancy any
+            # more, better log something into the error log and fall
+            # back gracefully.
+            environ['wsgi.errors'].write(
+                'Debugging middleware caught exception in streamed '
+                'response at a point where response headers were already '
+                'sent.\n')
+        else:
+            yield bytes_('Internal Server Error')
+
+    def _report_errors_with_response(self, environ, start_response):
+        self._report_errors(environ, None)
+        return self._generate_response(environ, start_response)
+
+    def _report_errors_while_consuming_iter(self, app_iter, environ, start_response):
+        try:
+            try:
+                for item in app_iter:
+                    yield item
+            finally:  # also after _report_errors_while_consuming_iter().close() injected GeneratorExit
+                if hasattr(app_iter, 'close'):
+                    app_iter.close()
+        except Exception:
+            for chunk in self._report_errors_with_response(environ, start_response):
+                yield chunk
+
+    def __call__(self, environ, start_response):
+        app_iter = None
+        try:
+            app_iter = self.app(environ, start_response)
+        except Exception:
+            return list(self._report_errors_with_response(environ, start_response))
+        else:
+            recorded_exc_info = environ.pop('backlash.exc_info', None)
+            if recorded_exc_info is not None:
+                environ = environ.pop('backlash.exc_environ', environ)
+                self._report_errors(environ, recorded_exc_info)
+
+        return self._report_errors_while_consuming_iter(app_iter, environ, start_response)

backlash/tracing/reporters/__init__.py

@@ -0,0 +1 @@
+  

backlash/tracing/reporters/mail.py

@@ -0,0 +1,126 @@
+from email.mime.application import MIMEApplication
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+import smtplib
+import ssl
+from backlash._compat import string_types, bytes_, text_, PY3
+
+
+class EmailReporter(object):
+    def __init__(self, smtp_server=None, from_address=None, error_email=None,
+                 smtp_username=None, smtp_password=None, smtp_use_tls=False,
+                 error_subject_prefix='', dump_request=False, dump_request_size=50000,
+                 dump_local_frames=False, dump_local_frames_count=2,
+                 smtp_port=None, **unused):
+        self.smtp_server = smtp_server
+        self.smtp_port = smtp_port
+        self.from_address = from_address
+
+        self.smtp_username = smtp_username
+        self.smtp_password = smtp_password
+
+        self.smtp_use_tls = smtp_use_tls
+
+        if isinstance(error_email, string_types):
+            error_email = error_email.split(",")
+        self.error_email = error_email
+
+        self.error_subject_prefix = error_subject_prefix
+        self.dump_request = dump_request
+        self.dump_request_size = dump_request_size
+        self.dump_local_frames = dump_local_frames
+        self.dump_local_frames_count = dump_local_frames_count
+
+        if not self.smtp_server or not self.from_address or not self.error_email:
+            raise ValueError("Backlash email reporting requires "
+                             "smtp_server, from_address and error_email settings") 
+
+    def report(self, traceback):
+        msg = self.assemble_email(traceback)
+
+        server = smtplib.SMTP(self.smtp_server, self.smtp_port)
+        if self.smtp_use_tls:
+            server.ehlo()
+            server.starttls()
+            server.ehlo()
+
+        if self.smtp_username and self.smtp_password:
+            server.login(self.smtp_username, self.smtp_password)
+
+        result = server.sendmail(self.from_address, self.error_email, msg.as_string())
+
+        try:
+            server.quit()
+        except ssl.SSLError:
+            # SSLError is raised in tls connections on closing sometimes
+            pass
+
+    def _repr_value(self, value):
+        try:
+            value = repr(value)
+        except Exception as e:
+            # Cope with WebOb response objects that might be unable to get their repr
+            value = repr(e)
+
+        if not PY3:
+            # On PY2 some repr might actually return bytes
+            # In that case just escape them.
+            value = value.decode('ascii', 'replace')
+
+        return value
+
+    def _format_cgi(self, environ):
+        return '\n'.join(
+            ('\t%s: %s' % (k, self._repr_value(environ[k])) for k in sorted(environ.keys()) if k.upper() == k))
+
+    def _format_wsgi(self, environ):
+        return '\n'.join(
+            ('\t%s: %s' % (k, self._repr_value(environ[k])) for k in sorted(environ.keys()) if k.upper() != k))
+
+    def email_body(self, traceback):
+        body = 'TRACEBACK:\n%s' % traceback.plaintext
+
+        if self.dump_local_frames:
+            body += '\n\n\nLAST FRAMES:'
+            frames_base_index = len(traceback.frames) - self.dump_local_frames_count
+            for idx, frame in enumerate(traceback.frames[-self.dump_local_frames_count:]):
+                body += '\n\tFRAME #%d\n' % (frames_base_index+idx)
+                for key, value in frame.locals.items():
+                    body += "\t\t%20s = " % key
+                    try:
+                        body += '%r\n' % (value,)
+                    except Exception as e:
+                        body += "<UNABLE TO PRINT VALUE>\n"
+
+        body += '\n\n\nENVIRON:\n%s' % self._format_cgi(traceback.context['environ'])
+        body += '\n\n\nWSGI:\n%s' % self._format_wsgi(traceback.context['environ'])
+
+        for entry, value in traceback.context.items():
+            if entry == 'environ':
+                continue
+
+            body += '\n\n\n%s:\n\t%r' % (entry.upper(), value)
+
+        return body
+
+    def assemble_email(self, traceback):
+        msg = MIMEMultipart()
+
+        subject = text_(traceback.exception)
+
+        msg['Subject'] = text_(self.error_subject_prefix + subject).replace('\n', ' ')
+        msg['From'] = text_(self.from_address)
+        msg['To'] = text_(', '.join(self.error_email))
+
+        text = MIMEText(bytes_(self.email_body(traceback)), 'plain', 'utf-8')
+        text.set_type('text/plain')
+        text.set_param('charset', 'UTF-8')
+        msg.attach(text)
+
+        request = traceback.context.get('request')
+        if self.dump_request and request is not None:
+            part = MIMEApplication(request.as_bytes(self.dump_request_size))
+            part.add_header('Content-Disposition', 'attachment; filename="request.txt"')
+            msg.attach(part)
+
+        return msg

backlash/tracing/reporters/sentry.py

@@ -0,0 +1,40 @@
+try:
+    from raven.base import Client
+    from raven.utils.wsgi import get_current_url, get_headers, get_environ
+except ImportError:
+    Client = None
+
+
+class SentryReporter(object):
+    def __init__(self, sentry_dsn, **unused):
+        if Client is None:
+            raise RavenNotAvailable('Raven is not installed, maybe run "pip install raven"')
+
+        self.client = Client(sentry_dsn)
+
+    def report(self, traceback):
+        environ = traceback.context.get('environ', {})
+        data = {
+            'sentry.interfaces.Http': {
+                'method': environ.get('REQUEST_METHOD'),
+                'url': get_current_url(environ, strip_querystring=True),
+                'query_string': environ.get('QUERY_STRING'),
+                # TODO
+                # 'data': environ.get('wsgi.input'),
+                'headers': dict(get_headers(environ)),
+                'env': dict(get_environ(environ)),
+            }
+        }
+
+        is_backlash_event = getattr(traceback.exc_value, 'backlash_event', False)
+        if is_backlash_event:
+            # Just a Stack Dump request from backlash
+            self.client.captureMessage(traceback.exception, data=data,
+                                       stack=traceback.frames)
+        else:
+            # This is a real crash
+            self.client.captureException(exc_info=traceback.exc_info, data=data)
+
+
+class RavenNotAvailable(Exception):
+    pass

backlash/tracing/slowrequests/__init__.py

@@ -0,0 +1 @@
+from .middleware import TraceSlowRequestsMiddleware

backlash/tracing/slowrequests/middleware.py

@@ -0,0 +1,113 @@
+import datetime as dt
+import os
+import threading
+import logging
+
+
+from backlash.tbtools import get_current_traceback
+from backlash.frtools import get_thread_stack, DumpThread
+from backlash.utils import RequestContext
+from .timer import Timer
+
+
+class TraceSlowRequestsMiddleware(object):
+
+    def __init__(self, app, reporters, context_injectors, interval=25,
+                 exclude_paths=None):
+
+        self.app = app
+        self.reporters = reporters
+        self.context_injectors = context_injectors
+        self.interval = interval
+        self.exclude_paths = exclude_paths or []
+
+        self.timer = Timer()
+        self.timer.daemon = True
+        self.timer.start()
+
+    def _stream_response(self, environ, data):
+        try:
+            for chunk in data:
+                yield chunk
+        finally:
+            if hasattr(data, 'close'):
+                data.close()
+            self._cancel_tracing(environ)
+
+    def __call__(self, environ, start_response):
+        try:
+            self._start_tracing(environ)
+            return self._stream_response(environ, self.app(environ, start_response))
+        except Exception:
+            self._cancel_tracing(environ)
+            raise
+
+    def peek(self, environ, thread_id, started):
+        context = RequestContext({'environ': dict(environ)})
+        for injector in self.context_injectors:
+            context.update(injector(environ))
+
+        context.update({
+            'SLOW_REQUEST': {'ThreadID': thread_id,
+                             'ProcessID': os.getpid(),
+                             'Started': str(started)}
+        })
+
+        try:
+            traceback = get_thread_stack(thread_id, environ.get('PATH_INFO', ''),
+                                         context=context, error_type='SlowRequestError')
+        except KeyError:
+            logging.warn('\nUnable to retrieve SlowRequest Stack %s, '
+                         'thread %s probably finished execution in mean time\n',
+                         environ.get('PATH_INFO', ''), thread_id)
+            return
+
+        for r in self.reporters:
+            try:
+                r.report(traceback)
+            except Exception:
+                error = get_current_traceback(skip=1, show_hidden_frames=False)
+                environ['wsgi.errors'].write('\nError while reporting slow request with %s\n' % r)
+                environ['wsgi.errors'].write(error.plaintext)
+
+    @classmethod
+    def _get_thread_id(cls):
+        return threading.current_thread().ident
+
+    def _is_exempt(self, environ):
+        """
+        Returns True if this request's URL starts with one of the
+        excluded paths.
+        """
+        exemptions = self.exclude_paths
+
+        if exemptions:
+            path = environ.get('PATH_INFO')
+            for excluded_p in self.exclude_paths:
+                if path.startswith(excluded_p):
+                    return True
+
+        return False
+
+    def _start_tracing(self, environ):
+        if not self._is_exempt(environ):
+            job = self.timer.run_later(self.peek,
+                                       self.interval,
+                                       environ,
+                                       self._get_thread_id(),
+                                       dt.datetime.utcnow())
+            # In some cases due to webob.Request.call_application() or
+            # paste StatusCodeRedirect middleware multiple _start_tracing for the same
+            # environ might happen without consuming the app_iter for the firsts
+            # and so without canceling them, we register them and cancel them all together.
+            environ.setdefault('BACKLASH_SLOW_TRACING_JOBS', []).append(job)
+
+    def _cancel_tracing(self, environ):
+        try:
+            tracing_jobs = environ.get('BACKLASH_SLOW_TRACING_JOBS', [])
+            for job in tracing_jobs:
+                self.timer.cancel(job)
+        except Exception:
+            error = get_current_traceback(skip=1, show_hidden_frames=False)
+            environ['wsgi.errors'].write('Failed to cancel slow requests tracing timer\n')
+            environ['wsgi.errors'].write(error.plaintext)

backlash/tracing/slowrequests/timer.py

@@ -0,0 +1,107 @@
+from functools import partial
+import logging
+import threading
+import time
+
+
+class TimerTask(object):
+
+    def __init__(self, callable_, *args, **kwargs):
+        self._callable = partial(callable_, *args, **kwargs)
+        self._finished = False
+
+    def is_finished(self):
+        return self._finished
+
+    def run(self):
+        try:
+            self._callable()
+        except:
+            logging.exception('TimerTask failed')
+        finally:
+            self._finished = True
+
+
+class Timer(threading.Thread):
+    """An alternative to threading.Timer. Where threading.Timer spawns a
+    dedicated thread for each job, this class uses a single, long-lived thread
+    to process multiple jobs.
+
+    Jobs are scheduled with a delay value in seconds.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super(Timer, self).__init__(*args, **kwargs)
+
+        self.lock = threading.Condition()
+        self._jobs = []
+        self.die = False
+
+    def run_later(self, callable_, timeout, *args, **kwargs):
+        """Schedules the specified callable for delayed execution.
+
+        Returns a TimerTask instance that can be used to cancel pending
+        execution.
+        """
+
+        self.lock.acquire()
+        try:
+            if self.die:
+                raise RuntimeError('This timer has been shut down and '
+                                   'does not accept new jobs.')
+
+            job = TimerTask(callable_, *args, **kwargs)
+            self._jobs.append((job, time.time() + timeout))
+            self._jobs.sort(key=lambda j: j[1])  # sort on time
+            self.lock.notify()
+
+            return job
+        finally:
+            self.lock.release()
+
+    def cancel(self, timer_task):
+        self.lock.acquire()
+        try:
+            self._jobs = list(filter(lambda job: job[0] is not timer_task,
+                                     self._jobs))
+            self.lock.notify()
+        finally:
+            self.lock.release()
+
+    def shutdown(self, cancel_jobs=False):
+        self.lock.acquire()
+        try:
+            self.die = True
+            if cancel_jobs:
+                self._jobs = []
+            self.lock.notify()
+        finally:
+            self.lock.release()
+
+    def _get_sleep_time(self):
+        if not self._jobs:
+            return 0
+        else:
+            job, scheduled_at = self._jobs[0]
+            return scheduled_at - time.time()
+
+    def run(self):
+        while True:
+            self.lock.acquire()
+            job = None
+            try:
+                if not self._jobs:
+                    if self.die:
+                        break
+                    else:
+                        self.lock.wait()
+                elif self._get_sleep_time() > 0:
+                    self.lock.wait(self._get_sleep_time())
+                else:
+                    job, timeout = self._jobs.pop(0)
+            finally:
+                self.lock.release()
+
+            if job:
+                # invoke the task without holding the lock
+                job.run()

backlash/utils.py

@@ -0,0 +1,42 @@
+from backlash._compat import text_type, binary_type
+from random import SystemRandom
+
+SALT_CHARS = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+
+_sys_rng = SystemRandom()
+
+def escape(s, quote=False):
+    """Replace special characters "&", "<" and ">" to HTML-safe sequences.  If
+    the optional flag `quote` is `True`, the quotation mark character is
+    also translated.
+
+    There is a special handling for `None` which escapes to an empty string.
+
+    :param s: the string to escape.
+    :param quote: set to true to also escape double quotes.
+    """
+    if s is None:
+        return ''
+    if hasattr(s, '__html__'):
+        return s.__html__()
+    if not isinstance(s, (text_type, binary_type)):
+        s = text_type(s)
+    if isinstance(s, binary_type):
+        try:
+            s.decode('ascii')
+        except:
+            s = s.decode('utf-8', 'replace')
+    s = s.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+    if quote:
+        s = s.replace('"', "&quot;")
+    return s
+
+def gen_salt(length):
+    """Generate a random string of SALT_CHARS with specified ``length``."""
+    if length <= 0:
+        raise ValueError('requested salt of length <= 0')
+    return ''.join(_sys_rng.choice(SALT_CHARS) for _ in range(length))
+
+class RequestContext(dict):
+    def __getattr__(self, attr):
+        return self[attr]

backlash-0.4.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: backlash
+Version: 0.4.0
+Summary: Standalone WebOb port of the Werkzeug Debugger with Python3 support meant to replace WebError in TurboGears2
+Author-email: Alessandro Molina <alessandro@molina.fyi>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TurboGears/backlash
+Keywords: wsgi,debugger,webob,python3,web
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+License-File: AUTHORS
+Requires-Dist: WebOb
+Dynamic: license-file
+
+About backlash
+-------------------------
+
+backlash is a swiss army knife for web applications debugging, which provides:
+
+- An Interactive In Browser Debugger based on a Werkzeug Debugger fork ported to WebOb
+- Crash reporting by email and on Sentry
+- Slow requests reporting by email and on Sentry.
+
+Backlash was born as a replacement for WebError in TurboGears2.3 versions.
+
+Installing
+-------------------------------
+
+backlash can be installed from pypi::
+
+    pip install backlash
+
+should just work for most of the users
+
+Debugging and Console
+----------------------------------
+
+Backlash supports both debugging applications on crash and realtime console,
+both are based on the Werkzeug Debugger and adapted to work with WebOb.
+
+The debugging function is provided by the ``DebuggedApplication`` middleware,
+wrapping your application with this middleware will intercept any exception
+and display the traceback and an interactive console in your browser.
+
+An interactive console will also be always available at ``/__console__`` path.
+
+Context Injectors
++++++++++++++++++++++++++++++
+
+The ``DebuggedApplication`` middleware also makes possible to provide one or more
+``context injectors``, those are simple python functions that will be called when
+an exception is raised to retrieve the context to store and make back available during
+debugging.
+
+Context injectors have to return a dictionary which will be merged into the current
+request context, the request context itself will be made available inside the debugger
+as the ``ctx`` object.
+
+This feature is used for example by TurboGears to provide back some of the objects
+which were available during execution like the current request.
+
+Example
++++++++++++++++++++++++++++++++
+
+The DebuggedApplication middleware is used by TurboGears in the following way::
+
+    def _turbogears_backlash_context(environ):
+        tgl = environ.get('tg.locals')
+        return {'request':getattr(tgl, 'request', None)}
+
+    app = backlash.DebuggedApplication(app, context_injectors=[_turbogears_backlash_context])
+
+
+Exception Tracing
+---------------------------------------
+
+The ``TraceErrorsMiddleware`` provides a WSGI middleware that intercepts any exception
+raised during execution, retrieves a traceback object and provides it to one or more
+``reporters`` to log the error.
+
+By default the ``EmailReporter`` and ``SentryReporter`` are provided to send error
+reports by email and on Sentry.
+
+The ``EmailReporter`` supports most of the options WebError ErrorMiddleware to provide some
+kind of backward compatibility and make possible a quick transition.
+
+While this function is easily replicable using the python logging SMTPHandler, the
+TraceErrorsMiddleware is explicitly meant for web applications crash reporting
+which has the benefit of being able to provide more complete information and keep a clear
+and separate process in managing errors.
+
+Example
+++++++++++++++++++++++++++++++++
+
+The TraceErrorsMiddleware is used by TurboGears in the following way::
+
+    from backlash.trace_errors import EmailReporter
+
+    def _turbogears_backlash_context(environ):
+       tgl = environ.get('tg.locals')
+       return {'request':getattr(tgl, 'request', None)}
+
+    app = backlash.TraceErrorsMiddleware(app, [EmailReporter(**errorware)],
+                                         context_injectors=[_turbogears_backlash_context])
+
+Slow Requests Tracing
+---------------------------------------
+
+The ``TraceSlowRequestsMiddleware`` provides a WSGI middleware that tracks requests
+execution time and reports requests that took more than a specified interval to complete
+(by default 25 seconds).
+
+It is also possible to exclude a list of paths that start with a specified string
+to avoid reporting long polling connections or other kind of requests that are
+expected to have a long life spawn.
+
+Example
+++++++++++++++++++++++++++++++++
+
+The TraceSlowRequestsMiddleware is used by TurboGears in the following way::
+
+    from backlash.trace_errors import EmailReporter
+
+    def _turbogears_backlash_context(environ):
+       tgl = environ.get('tg.locals')
+       return {'request':getattr(tgl, 'request', None)}
+
+    app = backlash.TraceSlowRequestsMiddleware(app, [EmailReporter(**errorware)],
+                                               interval=25, exclude_paths=None,
+                                               context_injectors=[_turbogears_backlash_context])